GetItem

On This Page

Description

Retrieves the requested attributes of a table item.

GetItem Read Optimization
Querying a table with GetItem is faster than a GetItems table scan, because GetItem searches for a specific object file on the data slice assigned to the item. See Working with NoSQL Data.

Request

Request Header

Syntax
    POST /<container>/<resource> HTTP/1.1
Host: <web-APIs URL>
Content-Type: application/json
X-v3io-function: GetItem
<Authorization OR X-v3io-session-key>: <value>

    url = "http://<web-APIs URL>/<container>/<resource>"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "GetItem",
            "<Authorization OR X-v3io-session-key>": "<value>"
          }
    URL Resource Parameters

    The path to the item to retrieve. The path includes the table path and the item's name (primary key). You can optionally set the item name in the request's Key JSON parameter instead of in the URL; you can also optionally set the relative table path within the container, or part of the path, in the request's TableName JSON parameter. See Data-Service Web-API General Structure.

    Request Data

    Syntax
      {
    "TableName":       "string",
    "Key": {
        "string": {
            "S":    "string",
            "N":    "string"
        }
    },
    "AttributesToGet": "string"
}

      payload = {
            "TableName":        "string",
            "Key": {
                "string": {
                    "S": "string",
                    "N": "string"
                }
            },
            "AttributesToGet":  "string"
          }
      Parameters
      TableName

      The table (collection) from which to retrieve the item — a relative table path within the configured data container or the end of such a path, depending on the resource configuration in the request URL. See Data-Service Web-API General Structure.

      • Type: String
      • Requirement: Required if not set in the request URL
      Key

      A primary-key attribute whose value is the item's primary-key value and name, which uniquely identifies the item within the table (see Item Name and Primary Key).

      Note

      To retrieve all items for an original sharding-key value that was recalculated during the ingestion (to achieve a more even workload distribution), you need to repeat the <api<GetItem request for each of the primary-key values that were used in the ingestion; (the primary-key value of the ingested item includes the recalculated sharding-key value). If the ingestion was done by using the even-distribution option of the NoSQL Spark DataFrame, you need to repeat the request with Key values that range from <original sharding key>_1.<sorting-key value> to <original sharding key>_<n>.<sorting-key value>, where <n> is the value of the v3io.kv.range-scan.hashing-bucket-num configuration property (default = 64); for example, johnd_1.20180602 .. johnd_64.20180602. For more information, see Recalculating Sharding-Key Values for Even Workload Distribution.

      • Requirement: Required if the item's name (primary key) is not set in the URL
      AttributesToGet

      The item attributes to return.

      • Type: String
      • Requirement: Optional
      • Default Value: "*"

      The attributes to return can be depicted in one of the following ways:

      • A comma-separated list of attribute names.
        Note: Currently, the delimiter commas cannot be surrounded by spaces.

        The attributes can be of any attribute type — user, system, or hidden.

      • "*" — retrieve the item's user attributes, but not its system or hidden attributes. This is the default value.

      • "**" — retrieve all item attributes — user, system, and hidden attributes.

      For an overview of the different attribute types, see Attribute Types.

      Response

      Response Data

      Syntax
      {
    "Item": {
        "string": {
            "S":    "string",
            "N":    "string",
            "BOOL": Boolean,
            "B":    "blob"
        }
    }
}
      Elements
      Item

      The requested item attributes. Only attributes that were requested in the request's AttributesToGet parameter are returned in the response.

      • Type: An item JSON object that contains zero or more Attribute objects

      Examples

      Retrieve from the MyDirectory/People table the Name, Age, and Country attributes of a person whose primary-key value is 1234:

      Request
        POST /mycontainer/MyDirectory/People/1234 HTTP/1.1
Host: https://default-tenant.app.mycluster.iguazio.com:8443
Content-Type: application/json
X-v3io-function: GetItem
X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf

        {
    "AttributesToGet": "Name,Age,Country"
}

        import requests

url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/MyDirectory/People/1234"
headers = {
            "Content-Type": "application/json",
            "X-v3io-function": "GetItem",
            "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
          }
payload = {"AttributesToGet": "Name,Age,Country"}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
        Response
        HTTP/1.1 200 OK
Content-Type: application/json
...

        {
    "Item": {
        "Age": {"N": "42"},
        "Country": {"S": "Zimbabwe"},
        "Name": {"S": "Shmerel"}
    }
}