Amazon DynamoDB Queries API

openapi: 3.2.0
info:
  title: Amazon Dynamodb Queries API
  version: '2012-08-10'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  description: 'Operations tagged Queries across 2 of this provider''s published API definitions: amazon-dynamodb-openapi.yml, amazon-dynamodb-queries-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://dynamodb.{region}.amazonaws.com
  description: Amazon DynamoDB Regional Endpoint
  variables:
    region:
      default: us-east-1
      description: AWS Region
tags:
- name: Queries
  description: Operations for querying and scanning table data
paths:
  /#Query:
    post:
      operationId: query
      summary: Amazon DynamoDB Query Items in a Table or Index
      description: Finds items based on primary key values. You can query a table or a secondary index. You must provide the name of the partition key attribute and a single value for that attribute. Query returns all items with that partition key value.
      tags:
      - Queries
      parameters:
      - $ref: '#/components/parameters/XAmzTarget'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/QueryInput'
            examples:
              queryRequestExample:
                summary: Default query request
                x-microcks-default: true
                value:
                  TableName: example-resource-name
                  IndexName: example-resource-name
                  KeyConditionExpression: example-string
                  FilterExpression: example-string
                  ProjectionExpression: example-string
      responses:
        '200':
          description: Successfully queried items
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/QueryOutput'
              examples:
                query200Example:
                  summary: Default query 200 response
                  x-microcks-default: true
                  value:
                    Items:
                    - {}
                    Count: 1
                    ScannedCount: 1
                    LastEvaluatedKey: {}
        '400':
          description: Invalid request parameters
        '404':
          description: Table not found
      x-amz-target: DynamoDB_20120810.Query
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - sigv4Auth: []
    servers:
    - url: https://dynamodb.{region}.amazonaws.com
      description: Amazon DynamoDB Regional Endpoint
      variables:
        region:
          default: us-east-1
          description: AWS Region
  /#Scan:
    post:
      operationId: scan
      summary: Amazon DynamoDB Scan Items in a Table or Index
      description: Returns one or more items and item attributes by accessing every item in a table or a secondary index. Scan operations proceed sequentially; however, for faster performance on a large table or secondary index, applications can use parallel scan.
      tags:
      - Queries
      parameters:
      - $ref: '#/components/parameters/XAmzTarget'
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/ScanInput'
            examples:
              scanRequestExample:
                summary: Default scan request
                x-microcks-default: true
                value:
                  TableName: example-resource-name
                  IndexName: example-resource-name
                  FilterExpression: example-string
                  ProjectionExpression: example-string
                  ExpressionAttributeNames: {}
      responses:
        '200':
          description: Successfully scanned items
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/ScanOutput'
              examples:
                scan200Example:
                  summary: Default scan 200 response
                  x-microcks-default: true
                  value:
                    Items:
                    - {}
                    Count: 1
                    ScannedCount: 1
                    LastEvaluatedKey: {}
        '400':
          description: Invalid request parameters
        '404':
          description: Table not found
      x-amz-target: DynamoDB_20120810.Scan
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - sigv4Auth: []
    servers:
    - url: https://dynamodb.{region}.amazonaws.com
      description: Amazon DynamoDB Regional Endpoint
      variables:
        region:
          default: us-east-1
          description: AWS Region
  /#ExecuteStatement:
    post:
      operationId: ExecuteStatement
      summary: Execute Statement
      description: This operation allows you to perform reads and singleton writes on data stored in DynamoDB, using PartiQL. For PartiQL reads (SELECT statement), if the total number of processed items exceeds the maximum dataset size limit of 1 MB, the read stops and results are returned to the user as a LastEvaluatedKey value to continue the read in a subsequent operation. If the filter criteria in WHERE clause does not match any data, the read will return an empty result set. A single SELECT statement response can return up to the maximum number of items (if using the Limit parameter) or a maximum of 1 MB of data (and then apply any filtering to the results using WHERE clause). If LastEvaluatedKey is present in the response, you need to paginate the result set. If NextToken is present, you need to paginate the result set and include NextToken.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/ExecuteStatementOutput'
        '400':
          description: ConditionalCheckFailedException; DuplicateItemException; ItemCollectionSizeLimitExceededException; ProvisionedThroughputExceededException; RequestLimitExceeded; ResourceNotFoundException; ThrottlingException; TransactionConflictException
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/ConditionalCheckFailedException'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - DynamoDB_20120810.ExecuteStatement
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/ExecuteStatementInput'
      tags:
      - Queries
      security:
      - sigv4: []
    servers:
    - url: https://dynamodb.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
  /#ExecuteTransaction:
    post:
      operationId: ExecuteTransaction
      summary: Execute Transaction
      description: This operation allows you to perform transactional reads or writes on data stored in DynamoDB, using PartiQL. The entire transaction must consist of either read statements or write statements, you cannot mix both in one transaction. The EXISTS function is an exception and can be used to check the condition of specific attributes of the item in a similar manner to ConditionCheck in the TransactWriteItems API.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/ExecuteTransactionOutput'
        '400':
          description: IdempotentParameterMismatchException; ProvisionedThroughputExceededException; RequestLimitExceeded; ResourceNotFoundException; ThrottlingException; TransactionCanceledException; TransactionInProgressException
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/IdempotentParameterMismatchException'
        '500':
          description: InternalServerError
          content:
            application/x-amz-json-1.0:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - DynamoDB_20120810.ExecuteTransaction
      requestBody:
        required: true
        content:
          application/x-amz-json-1.0:
            schema:
              $ref: '#/components/schemas/ExecuteTransactionInput'
      tags:
      - Queries
      security:
      - sigv4: []
    servers:
    - url: https://dynamodb.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
components:
  schemas:
    AttributeValue:
      type: object
      description: Represents the data for an attribute. Each attribute value is described as a name-value pair with the data type as the name.
      properties:
        S:
          type: string
          description: String attribute value
          example: example-string
        N:
          type: string
          description: Number attribute value (sent as string)
          example: example-string
        B:
          type: string
          format: byte
          description: Binary attribute value (Base64-encoded)
          example: example-string
        SS:
          type: array
          description: String set attribute value
          items:
            type: string
          example:
          - example-string
        NS:
          type: array
          description: Number set attribute value
          items:
            type: string
          example:
          - example-string
        BS:
          type: array
          description: Binary set attribute value
          items:
            type: string
            format: byte
          example:
          - example-string
        M:
          type: object
          description: Map attribute value
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
        L:
          type: array
          description: List attribute value
          items:
            $ref: '#/components/schemas/AttributeValue'
          example:
          - example-string
        'NULL':
          type: boolean
          description: Null attribute value
          example: true
        BOOL:
          type: boolean
          description: Boolean attribute value
          example: true
    ScanInput:
      type: object
      required:
      - TableName
      properties:
        TableName:
          type: string
          description: The name of the table to scan
          example: example-resource-name
        IndexName:
          type: string
          description: The name of a secondary index to scan
          example: example-resource-name
        FilterExpression:
          type: string
          description: A string that contains conditions for filtering the scan results
          example: example-string
        ProjectionExpression:
          type: string
          description: A string that identifies attributes to retrieve
          example: example-string
        ExpressionAttributeNames:
          type: object
          description: Substitution tokens for attribute names in an expression
          additionalProperties:
            type: string
          example: {}
        ExpressionAttributeValues:
          type: object
          description: Values that can be substituted in an expression
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
        Limit:
          type: integer
          description: The maximum number of items to evaluate
          minimum: 1
          example: 1
        ConsistentRead:
          type: boolean
          description: Determines the read consistency model
          example: true
        ExclusiveStartKey:
          type: object
          description: The primary key of the first item that this operation evaluates
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
        Segment:
          type: integer
          description: For parallel scan, identifies the segment to be scanned
          minimum: 0
          example: 1
        TotalSegments:
          type: integer
          description: For parallel scan, the total number of segments
          minimum: 1
          maximum: 1000000
          example: 1
        Select:
          type: string
          description: The attributes to be returned in the result
          enum:
          - ALL_ATTRIBUTES
          - ALL_PROJECTED_ATTRIBUTES
          - COUNT
          - SPECIFIC_ATTRIBUTES
          example: ALL_ATTRIBUTES
    QueryOutput:
      type: object
      properties:
        Items:
          type: array
          description: An array of item attributes that match the query criteria
          items:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/AttributeValue'
          example:
          - {}
        Count:
          type: integer
          description: The number of items in the response
          example: 1
        ScannedCount:
          type: integer
          description: The number of items evaluated before any filter is applied
          example: 1
        LastEvaluatedKey:
          type: object
          description: The primary key of the item where the operation stopped
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
    ScanOutput:
      type: object
      properties:
        Items:
          type: array
          description: An array of item attributes that match the scan criteria
          items:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/AttributeValue'
          example:
          - {}
        Count:
          type: integer
          description: The number of items in the response
          example: 1
        ScannedCount:
          type: integer
          description: The number of items evaluated before any filter is applied
          example: 1
        LastEvaluatedKey:
          type: object
          description: The primary key of the item where the operation stopped
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
    QueryInput:
      type: object
      required:
      - TableName
      properties:
        TableName:
          type: string
          description: The name of the table to query
          example: example-resource-name
        IndexName:
          type: string
          description: The name of a secondary index to query
          example: example-resource-name
        KeyConditionExpression:
          type: string
          description: The condition that specifies the key values for items to be retrieved
          example: example-string
        FilterExpression:
          type: string
          description: A string that contains conditions for filtering the query results
          example: example-string
        ProjectionExpression:
          type: string
          description: A string that identifies attributes to retrieve
          example: example-string
        ExpressionAttributeNames:
          type: object
          description: Substitution tokens for attribute names in an expression
          additionalProperties:
            type: string
          example: {}
        ExpressionAttributeValues:
          type: object
          description: Values that can be substituted in an expression
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
        ScanIndexForward:
          type: boolean
          description: Specifies the order for index traversal (true=ascending, false=descending)
          default: true
          example: true
        Limit:
          type: integer
          description: The maximum number of items to evaluate
          minimum: 1
          example: 1
        ConsistentRead:
          type: boolean
          description: Determines the read consistency model
          example: true
        ExclusiveStartKey:
          type: object
          description: The primary key of the first item that this operation evaluates
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue'
          example: {}
        Select:
          type: string
          description: The attributes to be returned in the result
          enum:
          - ALL_ATTRIBUTES
          - ALL_PROJECTED_ATTRIBUTES
          - COUNT
          - SPECIFIC_ATTRIBUTES
          example: ALL_ATTRIBUTES
    AttributeValue_2:
      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_2'
          description: 'An attribute of type Map. For example: "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}'
        L:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue_2'
          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.
    IdempotentParameterMismatchException:
      type: object
      properties:
        Message:
          type: string
    ConditionalCheckFailedException:
      type: object
      properties:
        message:
          type: string
          description: The conditional request failed.
        Item:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue_2'
          description: Item which caused the ConditionalCheckFailedException.
    ParameterizedStatement:
      type: object
      properties:
        Statement:
          type: string
          description: A PartiQL statement that uses parameters.
        Parameters:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue_2'
          description: The parameter values.
        ReturnValuesOnConditionCheckFailure:
          type: string
          enum:
          - ALL_OLD
          - NONE
          description: An optional parameter that returns the item attributes for a PartiQL ParameterizedStatement operation that failed a condition check. There is no additional cost associated with requesting a return value aside from the small network and processing overhead of receiving a larger response. No read capacity units are consumed.
      required:
      - Statement
    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.
    Capacity:
      type: object
      properties:
        ReadCapacityUnits:
          type: number
          description: The total number of read capacity units consumed on a table or an index.
        WriteCapacityUnits:
          type: number
          description: The total number of write capacity units consumed on a table or an index.
        CapacityUnits:
          type: number
          description: The total number of capacity units consumed on a table or an index.
    ExecuteTransactionInput:
      type: object
      properties:
        TransactStatements:
          type: array
          items:
            $ref: '#/components/schemas/ParameterizedStatement'
          description: The list of PartiQL statements representing the transaction to run.
        ClientRequestToken:
          type: string
          description: Set this value to get remaining results, if NextToken was returned in the statement response.
        ReturnConsumedCapacity:
          type: string
          enum:
          - INDEXES
          - TOTAL
          - NONE
          description: Determines the level of detail about either provisioned or on-demand throughput consumption that is returned in the response. For more information, see TransactGetItems and TransactWriteItems.
      required:
      - TransactStatements
    ItemResponse:
      type: object
      properties:
        Item:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue_2'
          description: Map of attribute data consisting of the data type and attribute value.
    InternalServerError:
      type: object
      properties:
        message:
          type: string
          description: The server encountered an internal error trying to fulfill the request.
    ExecuteStatementInput:
      type: object
      properties:
        Statement:
          type: string
          description: The PartiQL statement representing the operation to run.
        Parameters:
          type: array
          items:
            $ref: '#/components/schemas/AttributeValue_2'
          description: The parameters for the PartiQL statement, if any.
        ConsistentRead:
          type: boolean
          description: The consistency of a read operation. If set to true, then a strongly consistent read is used; otherwise, an eventually consistent read is used.
        NextToken:
          type: string
          description: Set this value to get remaining results, if NextToken was returned in the statement response.
        ReturnConsumedCapacity:
          type: string
          enum:
          - INDEXES
          - TOTAL
          - NONE
        Limit:
          type: integer
          description: The maximum number of items to evaluate (not necessarily the number of matching items). If DynamoDB processes the number of items up to the limit while processing the results, it stops the operation and returns the matching values up to that point, along with a key in LastEvaluatedKey to apply in a subsequent operation so you can pick up where you left off. Also, if the processed dataset size exceeds 1 MB before DynamoDB reaches this limit, it stops the operation and returns the matching values up to the limit, and a key in LastEvaluatedKey to apply in a subsequent operation to continue the op
        ReturnValuesOnConditionCheckFailure:
          type: string
          enum:
          - ALL_OLD
          - NONE
          description: An optional parameter that returns the item attributes for an ExecuteStatement operation that failed a condition check. There is no additional cost associated with requesting a return value aside from the small network and processing overhead of receiving a larger response. No read capacity units are consumed.
      required:
      - Statement
    ExecuteStatementOutput:
      type: object
      properties:
        Items:
          type: array
          items:
            type: object
            additionalProperties:
              $ref: '#/components/schemas/AttributeValue_2'
          description: If a read operation was used, this property will contain the result of the read operation; a map of attribute names and their values. For the write operations this value will be empty.
        NextToken:
          type: string
          description: If the response of a read request exceeds the response payload limit DynamoDB will set this value in the response. If set, you can use that this value in the subsequent request to get the remaining results.
        ConsumedCapacity:
          $ref: '#/components/schemas/ConsumedCapacity'
        LastEvaluatedKey:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/AttributeValue_2'
          description: The primary key of the item where the operation stopped, inclusive of the previous result set. Use this value to start a new operation, excluding this value in the new request. If LastEvaluatedKey is empty, then the "last page" of results has been processed and there is no more data to be retrieved. If LastEvaluatedKey is not empty, it does not necessarily mean that there is more data in the result set. The only way to know when you have reached the end of the result set is when LastEvaluatedKey is empty.
    ExecuteTransactionOutput:
      type: object
      properties:
        Responses:
          type: array
          items:
            $ref: '#/components/schemas/ItemResponse'
          description: The response to a PartiQL transaction.
        ConsumedCapacity:
          type: array
          items:
            $ref: '#/components/schemas/ConsumedCapacity'
          description: The capacity units consumed by the entire operation. The values of the list are ordered according to the ordering of the statements.
    ConsumedCapacity:
      type: object
      properties:
        TableName:
          type: string
          description: The name of the table that was affected by the operation. If you had specified the Amazon Resource Name (ARN) of a table in the input, you'll see the table ARN in the response.
        CapacityUnits:
          type: number
          description: The total number of capacity units consumed by the operation.
        ReadCapacityUnits:
          type: number
          description: The total number of read capacity units consumed by the operation.
        WriteCapacityUnits:
          type: number
          description: The total number of write capacity units consumed by the operation.
        Table:
          $ref: '#/components/schemas/Capacity'
        LocalSecondaryIndexes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Capacity'
          description: The amount of throughput consumed on each local index affected by the operation.
        GlobalSecondaryIndexes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Capacity'
          description: The amount of throughput consumed on each global index affected by the operation.
        VectorIndexes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/VectorCapacity'
          description: The amount of throughput consumed on each vector index affected by the operation. Each entry contains VectorWriteRequestBytes (for write operations) or VectorSearchRequestBytes (for search operations).
  parameters:
    XAmzTarget:
      name: X-Amz-Target
      in: header
      required: true
      description: The target DynamoDB operation, in the format DynamoDB_20120810.OperationName
      schema:
        type: string
        pattern: ^DynamoDB_20120810\.\w+$
  securitySchemes:
    sigv4Auth:
      type: http
      scheme: bearer
      description: AWS Signature Version 4 authentication
    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
externalDocs:
  description: Amazon DynamoDB API Reference
  url: https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/
x-refined-from:
- amazon-dynamodb-openapi.yml
- amazon-dynamodb-queries-api-openapi.yml