Amazon DynamoDB Dynamodb Operations API

openapi: 3.2.0
info:
  title: Amazon DynamoDB Operations API
  version: '2012-08-10'
  description: Generated from AWS's published Smithy model for Amazon DynamoDB. 2 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://dynamodb.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Operations
paths:
  /#SearchVectors:
    post:
      operationId: SearchVectors
      summary: Search Vectors
      description: 'Performs a vector similarity search on a vector index associated with an Amazon DynamoDB table, and returns the most similar items sorted by similarity score based on the distance function configured for the index. Score interpretation depends on the distance function: COSINE - Returns the items with the k smallest scores. Scores range from 0 (identical) to 2 (opposite). Lower scores indicate higher similarity. EUCLIDEAN - Returns the items with the k smallest scores. Scores represent the Euclidean distance between vectors. Lower scores indicate higher similarity. DOT_PRODUCT - Returns the items with the k highest scores. Higher scores indicate higher similarity.'
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/SearchVectorsOutput'
              example:
                SearchResults:
                - Item:
                    ProductName:
                      S: Wireless Headphones
                    Price:
                      N: '79.99'
                  Score: 0.95
                - Item:
                    ProductName:
                      S: Bluetooth Speaker
                    Price:
                      N: '49.99'
                  Score: 0.87
                - Item:
                    ProductName:
                      S: USB-C Hub
                    Price:
                      N: '34.99'
                  Score: 0.82
                ConsumedCapacity:
                  VectorSearchRequestBytes: 1024
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '400':
          description: RequestLimitExceeded; ResourceNotFoundException; ThrottlingException
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/RequestLimitExceeded'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - DynamoDB_20120810.SearchVectors
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/SearchVectorsInput'
            example:
              TableName: Products
              IndexName: cosine-product-idx
              SearchVector:
              - N: '0.12'
              - N: '0.85'
              - N: '0.44'
              - N: '0.67'
              TopK: 3
              SearchConditionExpression: Category = :cat
              ProjectionExpression: ProductName, Price
              ExpressionAttributeValues:
                :cat:
                  S: Electronics
              ReturnConsumedCapacity: INDEXES
      tags:
      - Operations
  /#UntagResource:
    post:
      operationId: UntagResource
      summary: Untag Resource
      description: Removes the association of tags from an Amazon DynamoDB resource. You can call UntagResource up to five times per second, per account. UntagResource is an asynchronous operation. If you issue a ListTagsOfResource request immediately after an UntagResource request, DynamoDB might return your previous tag set, if there was one, or an empty tag set. This is because ListTagsOfResource uses an eventually consistent query, and the metadata for your tags or table might not be available at that moment. Wait for a few seconds, and then try the ListTagsOfResource request again. The application or removal of tags using TagResource and UntagResource APIs is eventually consistent. ListTagsOfResource API will only reflect the changes after a few seconds. For an overview on tagging DynamoDB resources, see Tagging for DynamoDB in the Amazon DynamoDB Developer Guide.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.0:
              schema:
                type: string
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '421':
          description: InvalidEndpointException
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/InvalidEndpointException'
        '400':
          description: LimitExceededException; ResourceInUseException; ResourceNotFoundException
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - DynamoDB_20120810.UntagResource
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/UntagResourceInput'
      tags:
      - Operations
components:
  schemas:
    SearchVectorsOutput:
      type: object
      properties:
        ConsumedCapacity:
          $ref: '#/components/schemas/VectorCapacity'
        SearchResults:
          type: array
          items:
            $ref: '#/components/schemas/SearchResultItem'
          description: A list of items returned by the vector similarity search, sorted by similarity with the most similar item first. Each item contains the projected attributes and a similarity score.
    VectorCapacity:
      type: object
      properties:
        VectorSearchRequestBytes:
          type: number
          description: The number of vector search request bytes consumed by a SearchVectors operation.
        VectorWriteRequestBytes:
          type: number
          description: The number of vector write request bytes consumed when writing to a vector index. Reported for write operations that modify attributes indexed by a vector index.
    AttributeValue:
      type: object
      properties:
        S:
          type: string
          description: 'An attribute of type String. For example: "S": "Hello"'
        N:
          type: string
          description: 'An attribute of type Number. For example: "N": "123.45" Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.'
        B:
          type: string
          format: byte
          description: 'An attribute of type Binary. For example: "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"'
        SS:
          type: array
          items:
            type: string
          description: 'An attribute of type String Set. For example: "SS": ["Giraffe", "Hippo" ,"Zebra"]'
        NS:
          type: array
          items:
            type: string
          description: 'An attribute of type Number Set. For example: "NS": ["42.2", "-19", "7.5", "3.14"] Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.'
        BS:
          type: array
          items:
            type: string
            format: byte
          description: 'An attribute of type Binary Set. For example: "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]'
        M:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          description: 'An attribute of type Map. For example: "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}'
        L:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue'
          description: 'An attribute of type List. For example: "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]'
        'NULL':
          type: boolean
          description: 'An attribute of type Null. For example: "NULL": true'
        BOOL:
          type: boolean
          description: 'An attribute of type Boolean. For example: "BOOL": true'
      description: Exactly one member is set.
    RequestLimitExceeded:
      type: object
      properties:
        message:
          type: string
        ThrottlingReasons:
          type: array
          items:
            $ref: '#/components/schemas/ThrottlingReason'
          description: A list of ThrottlingReason that provide detailed diagnostic information about why the request was throttled.
    LimitExceededException:
      type: object
      properties:
        message:
          type: string
          description: Too many operations for a given subscriber.
    ThrottlingReason:
      type: object
      properties:
        reason:
          type: string
          description: 'The reason for throttling. The throttling reason follows a specific format: ResourceType+OperationType+LimitType: Resource Type (What is being throttled): Table or Index Operation Type (What kind of operation): Read or Write Limit Type (Why the throttling occurred): ProvisionedThroughputExceeded: The request rate is exceeding the provisioned throughput capacity (read or write capacity units) configured for a table or a global secondary index (GSI) in provisioned capacity mode. AccountLimitExceeded: The request rate has caused a table or global secondary index (GSI) in on-demand mode to exceed '
        resource:
          type: string
          description: The Amazon Resource Name (ARN) of the DynamoDB table or index that experienced the throttling event.
    UntagResourceInput:
      type: object
      properties:
        ResourceArn:
          type: string
          description: The DynamoDB resource that the tags will be removed from. This value is an Amazon Resource Name (ARN).
        TagKeys:
          type: array
          items:
            type: string
          description: A list of tag keys. Existing tags of the resource whose keys are members of this list will be removed from the DynamoDB resource.
      required:
      - ResourceArn
      - TagKeys
    SearchVectorsInput:
      type: object
      properties:
        TableName:
          type: string
          description: The name or Amazon Resource Name (ARN) of the table containing the vector index.
        IndexName:
          type: string
          description: The name of the vector index to search. The index must be in the ACTIVE state.
        ReturnConsumedCapacity:
          type: string
          enum:
          - INDEXES
          - TOTAL
          - NONE
        ExpressionAttributeNames:
          type: object
          additionalProperties:
            type: string
          description: 'One or more substitution tokens for attribute names in an expression. Use the # character in an expression to dereference an attribute name.'
        ExpressionAttributeValues:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          description: 'One or more values that can be substituted in an expression. Use the : character in an expression to dereference an attribute value.'
        ProjectionExpression:
          type: string
          description: A string that identifies one or more attributes to retrieve from the index. Separate attribute names with commas. If not specified, the operation returns all attributes projected into the vector index. Only attributes projected into the vector index can be retrieved.
        SearchVector:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue'
          description: The search vector to compare against the indexed vectors. Each element is a 32-bit IEEE-754 floating point number, provided in DynamoDB list format. The number of dimensions must match the number of dimensions configured for the vector index.
        SearchConditionExpression:
          type: string
          description: A condition expression used to filter the vector search results. The expression can reference attributes defined in the vector index search schema, including HASH and INLINE_FILTER key elements. Only the equality operator (=) is supported for HASH attributes. Comparison and range operators are supported for INLINE_FILTER attributes. Only top-level attributes from the search schema can be referenced.
        TopK:
          type: integer
          description: The number of most similar results to return.
      required:
      - TableName
      - IndexName
      - SearchVector
      - TopK
    SearchResultItem:
      type: object
      properties:
        Item:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          description: A map of attribute names to AttributeValue objects, representing the projected attributes of the item returned by the vector search.
        Score:
          type: number
          description: The similarity score for this item relative to the search vector. The interpretation depends on the distance function configured for the vector index.
    InternalServerError:
      type: object
      properties:
        message:
          type: string
          description: The server encountered an internal error trying to fulfill the request.
    InvalidEndpointException:
      type: object
      properties:
        Message:
          type: string
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: dynamodb
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/dynamodb/service/2012-08-10/dynamodb-2012-08-10.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)