Data API commands

This topic describes the commands you can perform with the Data API.

The sequence for running the commands is as follows:

  1. Start with the creation of a collection.

  2. Insert documents into a specified collection.

  3. Find data in documents.

  4. Update one or more documents.

  5. Delete one or more documents.

  6. Delete a collection, when needed.

Export environment variables

The curl commands in this topic use environment variables. If you haven’t already generated an auth token, you should go to Astra Portal now to generate one. It’s automatically associated with the Database Administrator role.

Then in the CLI of your choosing, before running the curl examples, export the values identified for your database in Astra Portal. Example:

export ASTRA_DB_API_ENDPOINT=API_ENDPOINT # Your database API endpoint
export ASTRA_DB_APPLICATION_TOKEN=TOKEN # Your database application token
export ASTRA_DB_KEYSPACE=default_keyspace # Your database keyspace
export ASTRA_DB_COLLECTION=collection # Your database collection

In the curl examples with Data API commands, notice:

  • The fully qualified POST url path — before the collection has been created, or when you want to find collections, or when you want to delete an existing collection — is: ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}`.

  • Once the collection has been created, the fully qualified POST url path for all other Data API commands is: ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}.

  • The createCollection example specifies vector_collection as the name.

    You can use a different name; be sure to assign it when you export the ASTRA_DB_COLLECTION environment variable, and modify the createCollection payload (the name property) as needed.

    You may define up to five collections for your Astra DB Serverless database.

    In your Terminal session, if you have defined multiple collections, keep track of the current collection to which you are submitting Data API commands.

About the default namespace/keyspace

Astra DB Serverless databases provide a default namespace, also known as a keyspace, called default_keyspace.

In this topic, we’ll use default_keyspace in the Data API curl examples via an ${ASTRA_DB_KEYSPACE} environment variable.

Manage collections

This section provides examples of Data API commands that manage collections:

  • createCollection

  • find Collections

  • deleteCollection

Create a vector-enabled collection

The following JSON payload is designed to create a new collection with specific configurations. You can have up to five collections per database.

This JSON structure is sent via an HTTP POST request to an Astra DB Serverless database. It creates a collection that is used to store vectors with specific properties.

The options in this createCollection command include the keyword vector, its dimension, its metric type, and an optional indexing clause.

An advanced feature is optional: the indexing clause and its mutually exclusive allow or deny array. If you omit the indexing clause entirely from the createCollection command, by default all properties in a document are indexed as they are added to the database. See important details in the section following the curl example.

By creating a vector-enabled collection, your apps can then store embeddings and perform AI similarity searches using subsequent Data API commands. See the examples that follow in this topic.

In each vector-enabled collection, you can define only one set of options that specify the dimension, metric, and optional indexing values.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "createCollection": {
    "name": "vector_collection",
    "options" : {
      "vector" : {
      "dimension" : 5,
      "metric" : "cosine"
      }
    }
  }
}' | json_pp
{
    "status": {
        "ok": 1
    }
}

About the command and each key-value pair:

  • createCollection: This is the main command that specifies that a new collection is to be created. It acts as a container for all the attributes and settings required to create the new collection.

  • name: The name of the new collection in this example is vector_collection. This is a string value that uniquely identifies the collection within the database.

  • options: This is a nested JSON object that holds additional settings for the new collection.

    • vector: Another nested JSON object under options that specifies properties for the vector space of the collection.

      • dimension: Indicates the dimension of the vectors to be stored in this collection. The value in this example is set to 5, which means each vector in this collection has five dimensions.

      • metric: Specifies the similarity metric to be used when querying or comparing vectors within this collection. The available options are dot_product, euclidean, and cosine. For details see Intro to vector databases. In this example’s payload, metric was set to cosine, which is used as the default similarity metric for this vector space.

      • indexing: (Optional) Determine which properties are indexed during subsequent update operations. If indexing is specified on createCollection, you must further specify one of the following, but not both. They are mutually exclusive.

        • allow : An array of one or more properties that are indexed; see the next section for important details.

        • deny: An array of one or more properties that are not indexed; see the next section for important details.

Advanced feature: indexing clause on createCollection

The createCollection command includes an optional indexing clause.

If you omit the indexing clause entirely from the createCollection command, by default all properties in the document are indexed when it is added or modified in the database. The index is implemented as a Storage-Attached Index (SAI), which enables Data API queries that filter and/or sort data based on the indexed property.

If you specify the indexing clause when you create a vector-enabled collection, you must include one (but not both) of the following: an allow or a deny array.

Pros and cons of selective indexing

It’s important to emphasize the pros and cons of allowing only certain properties to be indexed. While you may want to skip indexing certain properties to increase write-time performance, you’ll need to think ahead — when you create the collection — about which properties will be important to use in subsequent queries that rely on filtering and/or sort operations. You can only filter and/or sort the properties that have been indexed. Data API returns an error if you attempt to filter or sort a non-indexed property.

The error would have one of these formats:

UNINDEXED_FILTER_PATH("Unindexed filter path"), ...

UNINDEXED_SORT_PATH("Unindexed sort path"), ...

ID_NOT_INDEXED("_id is not indexed"), ...

Example:

UNINDEXED_FILTER_PATH("Unindexed filter path: The filter path ('address.city') is not indexed)"

While weighing the pros and cons of indexed or non-indexed properties in a document, consider the maximum size limits for those properties. Non-indexed properties allow for a much larger quantity of data, to accommodate data such as a blog post’s String content. In comparison, indexed properties are appropriately bound by lower maximum size limits to ensure efficient and performant read operations via the SAI index.

You’ll want to evaluate the pros and cons for each property in a document, and make decisions with the createCollection command’s indexing clause (if specified), based on the read/write and data capacity requirements of your apps.

Of course, test your app’s performance with the database including average and peak loads. If you need to adjust indexing options, try different settings in a newly defined collection and run tests again.

Document property example

Consider an example where the document has a total of 10 properties:

  • property1

  • property2

  • property3

    • property3.prop3a

    • property3.prop3b

  • property4

  • property5

    • property5.prop5a

    • property5.prop5b

    • property5.prop5c

The document also has an _id property, which is never indexed. It exists as the document’s primary key, allowing $eq and $in queries but not other operations.

We’ll look at the indexing behavior on the document’s properties in examples that follow. Keep those property names in mind.

Default example

Before we insert any documents in the database, let’s look again at a createCollection command that does not include an indexing clause:

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "createCollection": {
    "name": "vector_collection",
    "options" : {
      "vector" : {
      "dimension" : 5,
      "metric" : "cosine"
      }
    }
  }
}' | json_pp

In the preceding example, by default all properties will be indexed when documents are added or modified in the database. As a result, all properties may be referenced in filters and sort operations provided in subsequent commands, such as find, findOne, findOneAndUpdate, findOneAndReplace, and findOneAndDelete.

Indexing allow example

Now let’s look at an example where we want to use the indexing …​ allow clause:

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "createCollection": {
        "name": "vector_collection",
        "options": {
            "vector": {
                "dimension": 5,
                "metric": "cosine"
            },
            "indexing": {
                "allow": [
                    "property1",
                    "property2"
                ]
            }
        }
    }
}' | json_pp

In the preceding allow example, only the values of property1 and property2 are included in the SAI index. No other properties are indexed.

The net result for subsequent update operations:

Property name

Indexed?

property1

Yes

property2

Yes

property3

No

property3.prop3a

No

property3.prop3b

No

property4

No

property5

No

property5.prop5a

No

property5.prop5b

No

property5.prop5c

No

As a result, subsequent Data API queries may perform filtering and/or sort operations based only on property1, property2, or both.

Indexing deny example

Now let’s take an inverse approach with an indexing …​ deny array example:

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "createCollection": {
        "name": "vector_collection",
        "options": {
            "vector": {
                "dimension": 5,
                "metric": "cosine"
            },
            "indexing": {
                "deny": [
                    "property1",
                    "property3",
                    "property5.prop5b"
                ]
            }
        }
    }
}' | json_pp

In the preceding example, all the properties in the document are indexed except the ones listed in the deny clause.

Notice how the parent property3 was specified, which means its sub-properties property3.prop3a and property3.prop3b are also not indexed.

However, also notice how the specific sub-property named property5.prop5b was listed on the deny clause; which means property5.prop5b is not indexed, but the parent property5 and the sub-properties property5.prop5a and property5.prop5c are included in the SAI index.

The net result for subsequent update operations:

Property name

Indexed?

property1

No

property2

Yes

property3

No

property3.prop3a

No

property3.prop3b

No

property4

Yes

property5

Yes

property5.prop5a

Yes

property5.prop5b

No

property5.prop5c

Yes

Wildcard examples

The createCollection command’s optional indexing clause provides a convenience wildcard ["*"] in its syntax. For example, the following clause means that all properties will be indexed:

{
  "indexing": {
    "allow": ["*"]
  }
}

The preceding example is the equivalent of omitting the indexing clause. Meaning, all properties in the document will be indexed during update operations.

You can use the wildcard character with the deny clause:

{
  "indexing": {
    "deny": ["*"]
  }
}

In the preceding example, no properties are indexed, not even $vector.

Find collections

The following JSON payload contains the findCollections command and a Boolean option (explain) to indicate whether the response should contain more information, such as whether each listed collection is vector-enabled. This command is useful for getting an overview of the collections that are available for querying, insertion, or other database commands.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findCollections": {
    "options" : {
      "explain" : true
    }
  }
}' | json_pp
{
   "status" : {
      "collections" : [
         {
            "name" : "vector_collection",
            "options" : {
               "vector" : {
                  "dimension" : 5,
                  "metric" : "cosine"
               }
            }
         }
      ]
   }
}

About the command and its optional key-value pair:

  • The findCollections command specifies the action to be undertaken on the database. It’s a command directing the system to fetch details about the collections present in the database.

    • options: Under this key, an additional setting for the findCollections operation is specified.

      • "explain" : true: The explain option, when set to true, indicates that the operation should not just retrieve the names of collections, but also provide a brief explanation of metadata associated with each collection, such as whether the collection was created with the vector option. And for each vector-enabled collection, to further specify its dimension and metric values.

Delete a collection

The following JSON payload is designed to delete an existing collection. In this example, the command deletes a collection named vector_collection.

If you’re submitting the commands from this reference topic to your Astra DB Serverless database in sequence, skip this deleteCollection command for now. Instead, continue with the insert commands examples that follow this section.

This JSON payload is sent via an HTTP POST request to a server in order to delete a collection within an authenticated Astra DB Serverless database.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "deleteCollection": {
    "name": "vector_collection"
  }
}' | json_pp
{
    "status": {
        "ok": 1
    }
}

About the command and each key-value pair:

  • deleteCollection: This is the main command that specifies the collection to be deleted.

  • name: The name of the collection to be deleted. In this example, we are deleting the vector_collection. This is a string value that uniquely identifies the collection within the database.

Insert data

This section provides examples of Data API commands that insert data:

  • insertOne

  • insertMany

Insert one document with $vector

In the following example, $vector is a reserved property name for vector data.

This JSON payload is used for inserting a single document into a specified collection within an already authenticated vector-enabled Astra DB Serverless database. The payload is sent via an HTTP POST request to an API endpoint, represented by:

/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

Each document captures the details of a car purchase. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "insertOne": {
    "document": {
      "_id": "1",
      "purchase_type": "Online",
      "$vector": [0.25, 0.25, 0.25, 0.25, 0.25],
      "customer": {
        "name": "Jim A.",
        "phone": "123-456-1111",
        "age": 51,
        "credit_score": 782,
        "address": {
          "address_line": "1234 Broadway",
          "city": "New York",
          "state": "NY"
        }
      },
      "purchase_date": {"$date": 1690045891},
      "seller": {
        "name": "Jon B.",
        "location": "Manhattan NYC"
      },
      "items": [
        {
          "car" : "BMW 330i Sedan",
          "color": "Silver"
        },
        "Extended warranty - 5 years"
      ],
      "amount": 47601,
      "status" : "active",
      "preferred_customer" : true
    }
  }
}' | json_pp
{
    "status": {
        "insertedIds": [
            "1"
        ]
    }
}

About the command and each key-value pair:

  • insertOne: Data API designation that a single document is inserted.

    • document: Contains the details of the record added.

      • _id: A unique identifier for the document. It has a value of "1", which is essential to ensure each document in the collection can be uniquely identified.

      • purchase_type: Specifies how the purchase was made. In this context, the value is "Online", indicating it was an online purchase.

      • $vector: As noted, this is a reserved property used to store vector data. The value is an array of numbers [0.25, 0.25, 0.25, 0.25, 0.25]. These numbers could be used for various purposes like similarity searches, clustering, or other mathematical commands that can be applied to vectors. Given that this is a reserved property, the vector-enabled Astra DB Serverless database has specialized handling for data stored in this format. That is, optimized query performance for vector similarity.

      • customer: This nested object holds information about the customer who made the purchase.

        • name: The customer’s name is "Jim A.".

        • phone: The contact phone number for the customer.

        • age: The customer’s age. Subsequent examples can the customer.age property to demonstrate range and logical query operators such as $gt, $lt, and $not.

        • credit_score: The customer’s credit score at the time of the car’s purchase. Subsequent examples can use customer.credit_score to demonstrate range and logical query operators.

        • address: Contains further details about the customer’s address.

          • address_line: The main street or location address.

          • city and state: The city and state where the customer resides, which is New York, NY.

        • purchase_date: The date on which the purchase was made, using the $date operator and an Epoch value.

      • seller: Information about the seller from whom the purchase was made.

        • name: Seller’s name is "Jon B.".

        • location: The location of the seller, which in this document is "Manhattan NYC".

      • items: An array detailing the items included in this purchase.

        • The first entry in the array is an object indicating the purchase of a "BMW 330i Sedan" car that is silver in color.

        • The second entry is a string indicating that an "Extended warranty - 5 years" was also a part of the purchase.

      • amount: The total value of the purchase, which is $47,601.

      • status: Indicates the current status of the purchase, which is "active".

      • preferred_customer: A boolean flag indicating if the customer is a preferred one. The value "true" signifies that the customer is preferred.

Summary: This Data API command contains details of an online purchase made by a customer named "Jim A.". The purchase, valued at $47,601, includes a silver BMW 330i Sedan car and a 5-year extended warranty. The seller, "Jon B.", is located in Manhattan NYC, as is the customer. The purchase is currently active, and 51-year-old Jim, with a credit score of 782, is listed as a preferred customer.

By sending this JSON payload to the specified API endpoint, a new document with the given _id, name, $vector, and additional properties are created within the designated collection in the vector-enabled Astra DB Serverless database.

Use find to verify prior insertOne

The following JSON payload is designed to verify that the data inserted by the prior insertOne command was successfully stored in the database. The find {} represents a database query command.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find" : {}

}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About this request:

  • find: This command performs a search or query. The empty object {} inside the find key means that the query is broad and is meant to retrieve all documents from the specified collection without any filters or conditions.

  • This JSON payload is a request to fetch all records from a specific database collection without any filtering criteria.

Insert many documents with $vector

The following JSON payload inserts 20 more documents to the collection. As you may recall from Data API limits, 20 is the maximum number of documents that can be inserted per Data API command transaction.

The payload is structured for a car dealership or a similar business that sells vehicles, where purchases can include the car itself and additional services or warranties. Each transaction in the payload includes details about the purchase, the customer, the seller, and the items/services purchased.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

In the example’s Result tab, notice that the documents were inserted in a parallelized sequence, because "ordered" : false was specified in the POST request. The server was free to re-order the document inserts and parallelize them for performance. After the example, see the explanation of the ordered options for important details.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "insertMany": {
    "documents": [
      {
        "_id": "2",
        "purchase_type": "Online",
        "$vector": [0.1, 0.15, 0.3, 0.12, 0.05],
        "customer": {
          "name": "Jack B.",
          "phone": "123-456-2222",
        "age": 34,
        "credit_score": 700,
          "address": {
            "address_line": "888 Broadway",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1690391491},
        "seller": {
          "name": "Tammy S.",
          "location": "Staten Island NYC"
        },
        "items": [
            {
          "car" : "Tesla Model 3",
          "color": "White"
            },
            "Extended warranty - 10 years",
            "Service - 5 years"
        ],
        "amount": 53990,
      "status" : "active"
      },
      {
        "_id": "3",
        "purchase_type": "Online",
        "$vector": [0.15, 0.1, 0.1, 0.35, 0.55],
        "customer": {
          "name": "Jill D.",
          "phone": "123-456-3333",
        "age": 30,
        "credit_score": 742,
          "address": {
            "address_line": "12345 Broadway",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1690564291},
        "seller": {
          "name": "Jasmine S.",
          "location": "Brooklyn NYC"
        },
        "items": "Extended warranty - 10 years",
        "amount": 4600,
      "status" : "active"
      },
      {
        "_id": "4",
        "purchase_type": "In Person",
        "$vector": [0.25, 0.25, 0.25, 0.25, 0.26],
        "customer": {
          "name": "Lester M.",
          "phone": "123-456-4444",
        "age": 40,
        "credit_score": 802,
          "address": {
            "address_line": "12346 Broadway",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1690909891},
        "seller": {
          "name": "Jon B.",
          "location": "Manhattan NYC"
        },
        "items": [
            {
          "car" : "BMW 330i Sedan",
          "color": "Red"
            },
            "Extended warranty - 5 years",
            "Service - 5 years"
        ],
        "amount": 48510,
      "status" : "active"
      },
      {
        "_id": "5",
        "purchase_type": "Online",
        "$vector": [0.25, 0.045, 0.38, 0.31, 0.67],
        "customer": {
          "name": "David C.",
          "phone": "123-456-5555",
        "age": 50,
        "credit_score": 800,
          "address": {
            "address_line": "32345 Main Ave",
            "city": "Jersey City",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1690996291},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": [
          {
          "car" : "Tesla Model S",
          "color": "Red"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 94990,
      "status" : "active"
      },
      {
        "_id": "6",
        "purchase_type": "In Person",
        "$vector": [0.11, 0.02, 0.78, 0.10, 0.27],
        "customer": {
          "name": "Chris E.",
          "phone": "123-456-6666",
        "age": 43,
        "credit_score": 764,
          "address": {
            "address_line": "32346 Broadway",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1691860291},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": [
          {
          "car" : "Tesla Model X",
          "color": "Blue"
            }
        ],
        "amount": 109990,
      "status" : "active"
      },
      {
        "_id": "7",
        "purchase_type": "Online",
        "$vector": [0.21, 0.22, 0.33, 0.44, 0.53],
        "customer": {
          "name": "Jeff G.",
          "phone": "123-456-7777",
        "age": 66,
        "credit_score": 802,
          "address": {
            "address_line": "22999 Broadway",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1692119491},
        "seller": {
          "name": "Jasmine S.",
          "location": "Brooklyn NYC"
        },
        "items": [{
          "car" : "BMW M440i Gran Coupe",
          "color": "Black"
            },
            "Extended warranty - 5 years"],
        "amount": 61050,
      "status" : "active"
      },
      {
        "_id": "8",
        "purchase_type": "In Person",
        "$vector": [0.3, 0.23, 0.15, 0.17, 0.4],
        "customer": {
          "name": "Harold S.",
          "phone": "123-456-8888",
        "age": 29,
        "credit_score": 710,
          "address": {
            "address_line": "1234 Main St",
            "city": "Orange",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1693329091},
        "seller": {
          "name": "Tammy S.",
          "location": "Staten Island NYC"
        },
        "items": [{
          "car" : "BMW X3 SUV",
          "color": "Black"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 46900,
      "status" : "active"
      },
      {
        "_id": "9",
        "purchase_type": "Online",
        "$vector": [0.1, 0.15, 0.3, 0.12, 0.06],
        "customer": {
          "name": "Richard Z.",
          "phone": "123-456-9999",
        "age": 22,
        "credit_score": 690,
          "address": {
            "address_line": "22345 Broadway",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1693588291},
        "seller": {
          "name": "Jasmine S.",
          "location": "Brooklyn NYC"
        },
        "items": [{
          "car" : "Tesla Model 3",
          "color": "White"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 53990,
      "status" : "active"
      },
      {
        "_id": "10",
        "purchase_type": "In Person",
        "$vector": [0.25, 0.045, 0.38, 0.31, 0.68],
        "customer": {
          "name": "Eric B.",
          "phone": null,
        "age": 54,
        "credit_score": 780,
          "address": {
            "address_line": "9999 River Rd",
            "city": "Fair Haven",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1694797891},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": [{
          "car" : "Tesla Model S",
          "color": "Black"
            }
        ],
        "amount": 93800,
      "status" : "active"
      },
      {
        "_id": "11",
        "purchase_type": "Online",
        "$vector": [0.44, 0.11, 0.33, 0.22, 0.88],
        "customer": {
          "name": "Ann J.",
          "phone": "123-456-1112",
        "age": 47,
        "credit_score": 660,
          "address": {
            "address_line": "99 Elm St",
            "city": "Fair Lawn",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1695921091},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": [{
          "car" : "Tesla Model Y",
          "color": "White"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 57500,
      "status" : "active"
      },
      {
        "_id": "12",
        "purchase_type": "In Person",
        "$vector": [0.33, 0.44, 0.55, 0.77, 0.66],
        "customer": {
          "name": "John T.",
          "phone": "123-456-1123",
        "age": 55,
        "credit_score": 786,
          "address": {
            "address_line": "23 Main Blvd",
            "city": "Staten Island",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1696180291},
        "seller": {
          "name": "Tammy S.",
          "location": "Staten Island NYC"
        },
        "items": [{
          "car" : "BMW 540i xDrive Sedan",
          "color": "Black"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 64900,
      "status" : "active"
      },
      {
        "_id": "13",
        "purchase_type": "Online",
        "$vector": [0.1, 0.15, 0.3, 0.12, 0.07],
        "customer": {
          "name": "Aaron W.",
          "phone": "123-456-1133",
        "age": 60,
        "credit_score": 702,
          "address": {
            "address_line": "1234 4th Ave",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1697389891},
        "seller": {
          "name": "Jon B.",
          "location": "Manhattan NYC"
        },
        "items": [{
          "car" : "Tesla Model 3",
          "color": "White"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 55000,
      "status" : "active"
      },
      {
        "_id": "14",
        "purchase_type": "In Person",
        "$vector": [0.11, 0.02, 0.78, 0.21, 0.27],
        "customer": {
          "name": "Kris S.",
          "phone": "123-456-1144",
        "age": 44,
        "credit_score": 702,
          "address": {
            "address_line": "1414 14th Pl",
            "city": "Brooklyn",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1698513091},
        "seller": {
          "name": "Jasmine S.",
          "location": "Brooklyn NYC"
        },
        "items": [{
          "car" : "Tesla Model X",
          "color": "White"
            }
        ],
        "amount": 110400,
      "status" : "active"
      },
      {
        "_id": "15",
        "purchase_type": "Online",
        "$vector": [0.1, 0.15, 0.3, 0.12, 0.08],
        "customer": {
          "name": "Maddy O.",
          "phone": "123-456-1155",
        "age": 41,
        "credit_score": 782,
          "address": {
            "address_line": "1234 Maple Ave",
            "city": "West New York",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1701191491},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": {
          "car" : "Tesla Model 3",
          "color": "White"
            },
        "amount": 52990,
      "status" : "active"
      },
      {
        "_id": "16",
        "purchase_type": "In Person",
        "$vector": [0.44, 0.11, 0.33, 0.22, 0.88],
        "customer": {
          "name": "Tim C.",
          "phone": "123-456-1166",
        "age": 38,
        "credit_score": 700,
          "address": {
            "address_line": "1234 Main St",
            "city": "Staten Island",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1701450691},
        "seller": {
          "name": "Tammy S.",
          "location": "Staten Island NYC"
        },
        "items": [{
          "car" : "Tesla Model Y",
          "color": "White"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 58990,
      "status" : "active"
      },
      {
        "_id": "17",
        "purchase_type": "Online",
        "$vector": [0.1, 0.15, 0.3, 0.12, 0.09],
        "customer": {
          "name": "Yolanda Z.",
          "phone": "123-456-1177",
        "age": 61,
        "credit_score": 694,
          "address": {
            "address_line": "1234 Main St",
            "city": "Hoboken",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1702660291},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": [{
          "car" : "Tesla Model 3",
          "color": "Blue"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 54900,
      "status" : "active"
      },
      {
        "_id": "18",
        "purchase_type": "Online",
        "$vector": [0.15, 0.17, 0.15, 0.43, 0.55],
        "customer": {
          "name": "Thomas D.",
          "phone": "123-456-1188",
        "age": 45,
        "credit_score": 724,
          "address": {
            "address_line": "98980 20th St",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1703092291},
        "seller": {
          "name": "Jon B.",
          "location": "Manhattan NYC"
        },
        "items": [{
          "car" : "BMW 750e xDrive Sedan",
          "color": "Black"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 106900,
      "status" : "active"
      },
      {
        "_id": "19",
        "purchase_type": "Online",
        "$vector": [0.25, 0.25, 0.25, 0.25, 0.27],
        "customer": {
          "name": "Vivian W.",
          "phone": "123-456-1199",
        "age": 20,
        "credit_score": 698,
          "address": {
            "address_line": "5678 Elm St",
            "city": "Hartford",
            "state": "CT"
          }
        },
        "purchase_date": {"$date": 1704215491},
        "seller": {
          "name": "Jasmine S.",
          "location": "Brooklyn NYC"
        },
        "items": [{
          "car" : "BMW 330i Sedan",
          "color": "White"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 46980,
      "status" : "active"
      },
      {
        "_id": "20",
        "purchase_type": "In Person",
        "$vector": [0.44, 0.11, 0.33, 0.22, 0.88],
        "customer": {
          "name": "Leslie E.",
          "phone": null,
        "age": 44,
        "credit_score": 782,
          "address": {
            "address_line": "1234 Main St",
            "city": "Newark",
            "state": "NJ"
          }
        },
        "purchase_date": {"$date": 1705338691},
        "seller": {
          "name": "Jim A.",
          "location": "Jersey City NJ"
        },
        "items": [{
          "car" : "Tesla Model Y",
          "color": "Black"
            },
            "Extended warranty - 5 years"
        ],
        "amount": 59800,
      "status" : "active"
      },
      {
        "_id": "21",
        "purchase_type": "In Person",
        "$vector": [0.21, 0.22, 0.33, 0.44, 0.53],
        "customer": {
          "name": "Rachel I.",
          "phone": null,
        "age": 62,
        "credit_score": 786,
          "address": {
            "address_line": "1234 Park Ave",
            "city": "New York",
            "state": "NY"
          }
        },
        "purchase_date": {"$date": 1706202691},
        "seller": {
          "name": "Jon B.",
          "location": "Manhattan NYC"
        },
        "items": [{
          "car" : "BMW M440i Gran Coupe",
          "color": "Silver"
            },
            "Extended warranty - 5 years",
            "Gap Insurance - 5 years"
        ],
        "amount": 65250,
      "status" : "active"
      }
    ],
    "options": {
        "ordered": false
    }
  }
}' | json_pp
{
   "status" : {
      "insertedIds" : [
         "4",
         "7",
         "10",
         "13",
         "16",
         "19",
         "21",
         "18",
         "6",
         "12",
         "15",
         "9",
         "3",
         "11",
         "2",
         "17",
         "14",
         "8",
         "20",
         "5"
      ]
   }
}

About the command and each key-value pair:

  • insertMany: A command indicating multiple documents (or entries) are intended for insertion.

    • documents: An array of transaction records. Each record has the following properties:

      • _id: A unique identifier for the transaction. This is a primary key in the database.

      • purchase_type: Describes how the purchase was made, such as "Online" or "In Person".

      • $vector: A reserved property for storing vector data, containing an array that has the number of entries matching the dimension size (5 in this example) as previously specified with the createCollection command.

      • customer: Details of the customer involved in the purchase.

        • name: Name of the customer.

        • phone: Phone number of the customer. Some transactions have this property set to null, indicating that the phone number is not provided or not known.

        • age: The customer’s age. Subsequent examples can the customer.age property to demonstrate range and logical query operators such as $gt, $lt, and $not.

        • credit_score: The customer’s credit score at the time of the car’s purchase. Subsequent examples can use customer.credit_score to demonstrate range and logical query operators.

        • address: Contains details about the customer’s address.

          • address_line: Street address of the customer.

          • city: City of the customer.

          • state: State of the customer. Some transactions don’t have the address_line, just the city and state.

        • purchase_date: The date on which the purchase was made, using the $date operator and an Epoch value.

        • seller: Information about the seller or entity from which the purchase was made.

          • name: Name of the seller.

          • location: The location (such as the city and state or province) of the seller.

        • items: Describes the items/services purchased. This is an array or a single object. When it’s an array, it may contain a car object detailing the type of car and its color; or strings that detail other services or warranties, such as "Extended warranty - 10 years" or "Service - 5 years".

        • amount: Represents the total amount of the purchase in a numerical format.

        • status: The status of the transaction, such as "active".

    • options: Additional options for the insertMany command.

      • "ordered": false: When this ordered Boolean is false (the default), the server is free to re-order the inserts and parallelize them for performance; in this "fail silently" mode, one or more document(s) may fail to be inserted.

        If you specify "ordered": true, the server inserts the documents in sequential order, meaning each document must be successfully inserted before starting the next. Additionally, the command "fails fast" on the first document that fails to insert; in this case, the server does not continue inserting any remaining documents in the POST payload.

Find data

This section provides examples of Data API commands that find data using a variety of filter clauses, including filters with operators such as $eq, $ne, $and, $or, $gt, $gte, $lt, $lte, $all, $in, $nin, and $size:

  • find

  • findOne

Find all documents sorted by $vector

This JSON payload is designed to perform a vector search within an already authenticated vector-enabled Astra DB Serverless database. The payload is sent via an HTTP POST request to an API endpoint, represented by:

/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

As noted, $vector is a reserved property name for vector data.

The goal is to find and sort documents that are most similar to the specified vector, based on a similarity metric (such as cosine similarity, dot product, or Euclidean distance). In our example, recall that we defined this collection with the cosine metric.

This command is used often in AI applications such as content-based recommendation systems, similarity searches, clustering, and many other ML or data analysis tasks.

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "sort" : {"$vector" : [0.15, 0.1, 0.1, 0.35, 0.55]},
    "options" : {
        "limit" : 100
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.17,
               0.15,
               0.43,
               0.55
            ],
            "_id" : "18",
            "amount" : 106900,
            "customer" : {
               "address" : {
                  "address_line" : "98980 20th St",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 45,
               "credit_score" : 724,
               "name" : "Thomas D.",
               "phone" : "123-456-1188"
            },
            "items" : [
               {
                  "car" : "BMW 750e xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1703092291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "21",
            "amount" : 65250,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Park Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 62,
               "credit_score" : 786,
               "name" : "Rachel I.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years",
               "Gap Insurance - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1706202691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "7",
            "amount" : 61050,
            "customer" : {
               "address" : {
                  "address_line" : "22999 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 66,
               "credit_score" : 802,
               "name" : "Jeff G.",
               "phone" : "123-456-7777"
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1692119491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10",
            "amount" : 93800,
            "customer" : {
               "address" : {
                  "address_line" : "9999 River Rd",
                  "city" : "Fair Haven",
                  "state" : "NJ"
               },
               "age" : 54,
               "credit_score" : 780,
               "name" : "Eric B.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Black"
               }
            ],
            "purchase_date" : {
               "$date" : 1694797891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "20",
            "amount" : 59800,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Newark",
                  "state" : "NJ"
               },
               "age" : 44,
               "credit_score" : 782,
               "name" : "Leslie E.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1705338691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "16",
            "amount" : 58990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 38,
               "credit_score" : 700,
               "name" : "Tim C.",
               "phone" : "123-456-1166"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1701450691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.33,
               0.44,
               0.55,
               0.77,
               0.66
            ],
            "_id" : "12",
            "amount" : 64900,
            "customer" : {
               "address" : {
                  "address_line" : "23 Main Blvd",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 55,
               "credit_score" : 786,
               "name" : "John T.",
               "phone" : "123-456-1123"
            },
            "items" : [
               {
                  "car" : "BMW 540i xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1696180291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8",
            "amount" : 46900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Orange",
                  "state" : "NJ"
               },
               "age" : 29,
               "credit_score" : 710,
               "name" : "Harold S.",
               "phone" : "123-456-8888"
            },
            "items" : [
               {
                  "car" : "BMW X3 SUV",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693329091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19",
            "amount" : 46980,
            "customer" : {
               "address" : {
                  "address_line" : "5678 Elm St",
                  "city" : "Hartford",
                  "state" : "CT"
               },
               "age" : 20,
               "credit_score" : 698,
               "name" : "Vivian W.",
               "phone" : "123-456-1199"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1704215491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.26
            ],
            "_id" : "4",
            "amount" : 48510,
            "customer" : {
               "address" : {
                  "address_line" : "12346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 40,
               "credit_score" : 802,
               "name" : "Lester M.",
               "phone" : "123-456-4444"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Red"
               },
               "Extended warranty - 5 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690909891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.07
            ],
            "_id" : "13",
            "amount" : 55000,
            "customer" : {
               "address" : {
                  "address_line" : "1234 4th Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 60,
               "credit_score" : 702,
               "name" : "Aaron W.",
               "phone" : "123-456-1133"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1697389891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.21,
               0.27
            ],
            "_id" : "14",
            "amount" : 110400,
            "customer" : {
               "address" : {
                  "address_line" : "1414 14th Pl",
                  "city" : "Brooklyn",
                  "state" : "NY"
               },
               "age" : 44,
               "credit_score" : 702,
               "name" : "Kris S.",
               "phone" : "123-456-1144"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "White"
               }
            ],
            "purchase_date" : {
               "$date" : 1698513091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.06
            ],
            "_id" : "9",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "22345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 22,
               "credit_score" : 690,
               "name" : "Richard Z.",
               "phone" : "123-456-9999"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693588291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.1,
               0.27
            ],
            "_id" : "6",
            "amount" : 109990,
            "customer" : {
               "address" : {
                  "address_line" : "32346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 43,
               "credit_score" : 764,
               "name" : "Chris E.",
               "phone" : "123-456-6666"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "Blue"
               }
            ],
            "purchase_date" : {
               "$date" : 1691860291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command indicates that a "find" command is to be performed. It holds nested JSON objects that define the search and sort criteria.

    • sort: This clause specifies the vector against which other vectors in the database are compared. The $vector is a reserved property name for storing vector data, and here it’s set to [0.15, 0.1, 0.1, 0.35, 0.55]. The vector-enabled Astra DB Serverless database uses this vector to perform a similarity search among the documents, sorting them based on how similar their $vector values are to this specified vector.

    • options: This is another nested JSON object that holds additional settings for the "find" command.

      • limit: This property specifies the maximum number of documents that the query should return. It is set to 100 in this example; meaning that the search returns up to 100 of the most similar documents, sorted according to their similarity to the specified vector.

Find sorted by $vector search, projection enabled, return similarity scores

This JSON payload is designed to perform a vector-based search with projection in an vector-enabled Astra DB Serverless database. The payload is sent via an HTTP POST request to an API endpoint, represented by:

/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

As noted, $vector is a reserved property name for vector data.

The command aims to find and sort documents that are most similar to the specified vector, based on a similarity metric, and to project specific properties from those documents in the response. The $similarity score (such as 0.99444735) is useful for understanding how close each result is to the queried vector.

  • A value of 0 indicates that the vectors are diametrically opposed.

  • A value of 0.5 suggests the vectors are orthogonal (or perpendicular) and have no match.

  • A value of 1 indicates that the vectors are identical in direction.

Additionally, in this example response, only the $vector and $similarity properties are returned for each document, making the output more focused and potentially reducing the amount of data transferred.

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "sort" : {"$vector" : [0.15, 0.1, 0.1, 0.35, 0.55]},
    "projection" : {"$vector" : 1},
    "options" : {
        "includeSimilarity" : true,
        "limit" : 100
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$similarity" : 1,
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3"
         },
         {
            "$similarity" : 0.9953563,
            "$vector" : [
               0.15,
               0.17,
               0.15,
               0.43,
               0.55
            ],
            "_id" : "18"
         },
         {
            "$similarity" : 0.9732053,
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "21"
         },
         {
            "$similarity" : 0.9732053,
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "7"
         },
         {
            "$similarity" : 0.96955204,
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10"
         },
         {
            "$similarity" : 0.9691053,
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5"
         },
         {
            "$similarity" : 0.9600924,
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11"
         },
         {
            "$similarity" : 0.9600924,
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "20"
         },
         {
            "$similarity" : 0.9600924,
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "16"
         },
         {
            "$similarity" : 0.9468591,
            "$vector" : [
               0.33,
               0.44,
               0.55,
               0.77,
               0.66
            ],
            "_id" : "12"
         },
         {
            "$similarity" : 0.94535017,
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8"
         },
         {
            "$similarity" : 0.9163125,
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19"
         },
         {
            "$similarity" : 0.91263497,
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.26
            ],
            "_id" : "4"
         },
         {
            "$similarity" : 0.9087937,
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1"
         },
         {
            "$similarity" : 0.7909429,
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17"
         },
         {
            "$similarity" : 0.7820388,
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15"
         },
         {
            "$similarity" : 0.77284586,
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.07
            ],
            "_id" : "13"
         },
         {
            "$similarity" : 0.7711377,
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.21,
               0.27
            ],
            "_id" : "14"
         },
         {
            "$similarity" : 0.76337516,
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.06
            ],
            "_id" : "9"
         },
         {
            "$similarity" : 0.75363994,
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2"
         },
         {
            "$similarity" : 0.74406904,
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.1,
               0.27
            ],
            "_id" : "6"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command indicates that a "find" or search command is to be executed. It contains nested JSON objects that define the search criteria, projection, and other options.

    • sort: This clause specifies the vector against which other vectors in the vector-enabled Astra DB Serverless database are to be compared. The $vector key is a reserved property name for storing vector data. The vector is set to [0.15, 0.1, 0.1, 0.35, 0.55]. Documents in the database are sorted based on their similarity to this vector.

    • projection: This property is used to specify which properties should be included in the returned documents.

      • $vector: Setting this value to 1 means that the $vector values are included in the output.

    • options: This nested JSON object contains additional settings for the "find" command.

      • includeSimilarity: Setting this boolean to true means that the response includes a $similarity score, representing the similarity metric between the sorted vector and the vectors in the database. The returned scores (such as 0.99444735) are useful for understanding how close each result is to the queried vector.

        • A value of 0 indicates that the vectors are diametrically opposed.

        • A value of 0.5 suggests the vectors are orthogonal (or perpendicular) and have no match.

        • A value of 1 indicates that the vectors are identical in direction.

      • limit: Specifies the maximum number of documents to be returned. It’s set to 100, meaning the search returns up to the top 100 most similar documents.

Find one sorted by specific $vector and projection enabled

This JSON payload is structured to execute a findOne command with vector-based search criteria in an vector-enabled Astra DB Serverless database.

The purpose is to find and return a single document that is most similar to the specified vector based on a particular similarity metric, such as cosine similarity, dot product, or Euclidean distance. In our example, recall that we defined this collection with the cosine function.

The payload is sent via an HTTP POST request to an API endpoint, represented by:

/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

As noted, $vector is a reserved property name for vector data.

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOne": {
    "sort" : {"$vector" : [0.15, 0.1, 0.1, 0.35, 0.55]},
    "projection" : {"$vector" : 1}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "$vector" : [
            0.15,
            0.1,
            0.1,
            0.35,
            0.55
         ],
         "_id" : "3"
      }
   }
}

About the command and each key-value pair:

  • findOne: This command signifies that the command aims to find a single document. The value is a nested JSON object that defines how to sort and project the results.

    • sort: This clause is used to specify the vector against which other vectors in the database are compared for similarity. The $vector key is a reserved property name for storing vector data. Here, it’s set to the array [0.15, 0.1, 0.1, 0.35, 0.55]. The vector-enabled Astra DB Serverless database uses this vector to find the document whose $vector property is most similar to the specified array.

    • projection: This nested JSON object specifies which properties should be included in the returned document.

      • $vector: Setting this property to 1 means that the $vector array values are included in the output, allowing you to see the vector data and _id of the returned document.

Find one with filter using a document’s _id

The following JSON payload is designed to get a purchase by a document’s _id value.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOne": {
    "filter": {"_id" : "14"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "$vector" : [
            0.11,
            0.02,
            0.78,
            0.21,
            0.27
         ],
         "_id" : "14",
         "amount" : 110400,
         "customer" : {
            "address" : {
               "address_line" : "1414 14th Pl",
               "city" : "Brooklyn",
               "state" : "NY"
            },
            "age" : 44,
            "credit_score" : 702,
            "name" : "Kris S.",
            "phone" : "123-456-1144"
         },
         "items" : [
            {
               "car" : "Tesla Model X",
               "color" : "White"
            }
         ],
         "purchase_date" : {
            "$date" : 1698513091
         },
         "purchase_type" : "In Person",
         "seller" : {
            "location" : "Brooklyn NYC",
            "name" : "Jasmine S."
         },
         "status" : "active"
      }
   }
}

About the command and each key-value pair:

  • findOne: This command finds a particular document that matches a specified query criterion.

    • filter: This clause is used to specify the criteria that determine which document the database should return.

    • _id : "14": Here, a specific filter criterion is looking for the document with an ID of 14.

Find one query using index filtered by purchase_date

The following JSON payload is designed to get one document where the purchase_date is the 12/20/2023, using a known Epoch value of 1703092291 as specified with $date in the insertMany example.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "findOne": {
        "filter": {
            "purchase_date": {
                "$date": 1703092291
            }
        }
    }
}' | json_pp
{
   "data" : {
      "document" : {
         "$vector" : [
            0.15,
            0.17,
            0.15,
            0.43,
            0.55
         ],
         "_id" : "18",
         "amount" : 106900,
         "customer" : {
            "address" : {
               "address_line" : "98980 20th St",
               "city" : "New York",
               "state" : "NY"
            },
            "age" : 45,
            "credit_score" : 724,
            "name" : "Thomas D.",
            "phone" : "123-456-1188"
         },
         "items" : [
            {
               "car" : "BMW 750e xDrive Sedan",
               "color" : "Black"
            },
            "Extended warranty - 5 years"
         ],
         "purchase_date" : {
            "$date" : 1703092291
         },
         "purchase_type" : "Online",
         "seller" : {
            "location" : "Manhattan NYC",
            "name" : "Jon B."
         },
         "status" : "active"
      }
   }
}

About the command and each key-value pair:

  • findOne: This command is designed to fetch a single document that matches certain query parameters.

    • filter: This clause defines the criteria that the query uses to determine which document should be returned from the database.

      • "purchase_date" : "12/31/2022": This clause represents the date on which an item was purchased or an order was placed.

To summarize, this JSON payload is instructing the Astra DB Serverless database to execute a findOne command to retrieve a single document where the purchase_date property is equal to "12/31/2022".

Find multiple documents filtered by purchase_type

The following JSON payload is designed to return multiple documents by getting purchases by a given purchase_type value.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {"purchase_type": "Online"}
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.17,
               0.15,
               0.43,
               0.55
            ],
            "_id" : "18",
            "amount" : 106900,
            "customer" : {
               "address" : {
                  "address_line" : "98980 20th St",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 45,
               "credit_score" : 724,
               "name" : "Thomas D.",
               "phone" : "123-456-1188"
            },
            "items" : [
               {
                  "car" : "BMW 750e xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1703092291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.07
            ],
            "_id" : "13",
            "amount" : 55000,
            "customer" : {
               "address" : {
                  "address_line" : "1234 4th Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 60,
               "credit_score" : 702,
               "name" : "Aaron W.",
               "phone" : "123-456-1133"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1697389891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.06
            ],
            "_id" : "9",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "22345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 22,
               "credit_score" : 690,
               "name" : "Richard Z.",
               "phone" : "123-456-9999"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693588291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "7",
            "amount" : 61050,
            "customer" : {
               "address" : {
                  "address_line" : "22999 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 66,
               "credit_score" : 802,
               "name" : "Jeff G.",
               "phone" : "123-456-7777"
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1692119491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19",
            "amount" : 46980,
            "customer" : {
               "address" : {
                  "address_line" : "5678 Elm St",
                  "city" : "Hartford",
                  "state" : "CT"
               },
               "age" : 20,
               "credit_score" : 698,
               "name" : "Vivian W.",
               "phone" : "123-456-1199"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1704215491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria, as opposed to "findOne", which retrieves a single document.

    • filter: This clause is used to specify the criteria that the query uses to select documents in a database.

      • "purchase_type": "Online": This clause is used to query for documents where the purchase was made online.

In the response, notice the nextPageState is null, because fewer than 21 documents were returned from the query. The maximum for each page is 20.

Find using property stored in an array, filtered by warranty type

The following JSON payload is designed to get purchases where items = "Extended warranty - 10 years".

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {"items" : "Extended warranty - 10 years"}
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: This clause contains the criteria that the find command uses to fetch documents from the database.

      • "items": "Extended warranty - 10 years": This clause is a key-value pair inside the "filter" object, specifying the condition for the search. Here, items is a property that may be present in the documents, denoting the type or description of items. The value "Extended warranty - 10 years" indicates that the search is for documents where the items property contains this exact string.

Find with multi-column filter for customers from specific city and state

The following JSON payload uses two properties, customer.address.city and customer.address.state, in a filter that looks for car sales by customers in Hoboken, NJ.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "customer.address.city": "Hoboken",
      "customer.address.state": "NJ"
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: This clause contains the criteria that the find command uses to fetch documents from the database.

      • customer.address.city and customer.address.state: Query finds customers from Hoboken, NJ.

Find with $and $or to filter whether seller and customer match given values

The following JSON payload uses the $and and $or logical operators to find documents where the customer’s city is either "Jersey City" or "Orange" AND the seller’s name is either "Jim A." or "Tammy S.". For a document to be returned, both these primary conditions (customer’s city and seller’s name) must be met.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find": {
        "filter": {
            "$and": [
                {
                    "$or": [
                        {
                            "customer.address.city": "Jersey City"
                        },
                        {
                            "customer.address.city": "Orange"
                        }
                    ]
                },
                {
                    "$or": [
                        {
                            "seller.name": "Jim A."
                        },
                        {
                            "seller.name": "Tammy S."
                        }
                    ]
                }
            ]
        }
    }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8",
            "amount" : 46900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Orange",
                  "state" : "NJ"
               },
               "age" : 29,
               "credit_score" : 710,
               "name" : "Harold S.",
               "phone" : "123-456-8888"
            },
            "items" : [
               {
                  "car" : "BMW X3 SUV",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693329091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from collections based on specified criteria.

    • filter: This clause contains the criteria that the find command uses to fetch documents from the database.

      • $and: A logical operator that ensures all nested conditions must be met for a record to be returned.

        • The first condition within the $and array:

          $or: A logical operator where any one of the nested conditions must be met.

          The first nested condition checks if the customer.address.city property is equal to "Jersey City".

          The second nested condition checks if the customer.address.city property is equal to "Orange".

        • The second condition within the $and array:

          $or: Any one of the nested conditions must be met.

          The first nested condition checks if the seller.name property is equal to "Jim A.".

          The second nested condition checks if the seller.name property is equal to "Tammy S.".

Summary: The example shows nested conditions with $and and $or logical operators to find documents where the customer’s city is either "Jersey City" or "Orange" AND the seller’s name is either "Jim A." or "Tammy S.". For a document to be returned, both these primary conditions (customer’s city and seller’s name) must be met.

Find with $in to query city

The following JSON payload uses the $in query operator to find documents where one or more customers have an address that contains the city of "Hoboken" or "Fair Haven".

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find": {
        "filter": {
            "customer.address.city": {
                "$in": [
                    "Hoboken",
                    "Fair Haven"
                ]
            }
        }
    }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10",
            "amount" : 93800,
            "customer" : {
               "address" : {
                  "address_line" : "9999 River Rd",
                  "city" : "Fair Haven",
                  "state" : "NJ"
               },
               "age" : 54,
               "credit_score" : 780,
               "name" : "Eric B.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Black"
               }
            ],
            "purchase_date" : {
               "$date" : 1694797891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • "customer.address.city": This key suggests a hierarchical data structure. It implies that within the targeted records, there’s an expected customer field, within which there’s an address field, and within that, a city field. This kind of dot-notation is common in NoSQL databases like MongoDB for querying nested fields.

      • $in: This query operator is used to specify that the ensuing search should match any documents where the value of customer.address.city is equal to any value in the provided array.

      • The array ["Hoboken", "Fair Haven"] lists the values to be matched against the customer.address.city property.

Summary: This Data API command is instructing the server to query a database, retrieving all records where the city property of a customer’s address is either "Hoboken" or "Fair Haven". This query returns all documents that have either of these two values in the customer.address.city property.

Find with $exists where property is present

The following JSON payload uses the $exists query operator to find documents where the buyer is a preferred customer.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "preferred_customer": {
        "$exists": true
      }
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • preferred_customer: This key represents a specific property within the documents or records in the database. The query focuses on this property.

      • $exists: This query operator is used to check the presence of the "preferred_customer" property in the documents.

      • true: This is the value assigned to the $exists query operator, indicating that the query should return documents where the preferred_customer property exists, regardless of what value it holds.

Find with $eq where document equals purchases by given seller’s name and location

The following JSON payload uses the $eq query operator to find documents where the seller is "Jasmine S." and she is located in "Brooklyn NYC".

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "seller": {
        "$eq": {
          "name": "Jasmine S.",
          "location": "Brooklyn NYC"
        }
      }
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.21,
               0.27
            ],
            "_id" : "14",
            "amount" : 110400,
            "customer" : {
               "address" : {
                  "address_line" : "1414 14th Pl",
                  "city" : "Brooklyn",
                  "state" : "NY"
               },
               "age" : 44,
               "credit_score" : 702,
               "name" : "Kris S.",
               "phone" : "123-456-1144"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "White"
               }
            ],
            "purchase_date" : {
               "$date" : 1698513091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.06
            ],
            "_id" : "9",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "22345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 22,
               "credit_score" : 690,
               "name" : "Richard Z.",
               "phone" : "123-456-9999"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693588291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "7",
            "amount" : 61050,
            "customer" : {
               "address" : {
                  "address_line" : "22999 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 66,
               "credit_score" : 802,
               "name" : "Jeff G.",
               "phone" : "123-456-7777"
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1692119491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19",
            "amount" : 46980,
            "customer" : {
               "address" : {
                  "address_line" : "5678 Elm St",
                  "city" : "Hartford",
                  "state" : "CT"
               },
               "age" : 20,
               "credit_score" : 698,
               "name" : "Vivian W.",
               "phone" : "123-456-1199"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1704215491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • seller: This key represents a specific property within the documents in the database, indicating that the query is applied to this field.

        • $eq: This query operator is used to compare for equality.

        • name: "Jasmine B." and "location": "Brooklyn NYC" are nested within the $eq operator, forming an object. The intention is to match documents where the seller property equals this exact object.

Find with $ne where documents have cars purchased by customers not residing in New York

The following JSON payload uses the $ne (not equal) query operator to find documents where the cars were purchased by customers who do not reside in New York (NY) state.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find": {
        "filter": {
            "customer.address.state": {
                "$ne": "NY"
            }
        }
    }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10",
            "amount" : 93800,
            "customer" : {
               "address" : {
                  "address_line" : "9999 River Rd",
                  "city" : "Fair Haven",
                  "state" : "NJ"
               },
               "age" : 54,
               "credit_score" : 780,
               "name" : "Eric B.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Black"
               }
            ],
            "purchase_date" : {
               "$date" : 1694797891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8",
            "amount" : 46900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Orange",
                  "state" : "NJ"
               },
               "age" : 29,
               "credit_score" : 710,
               "name" : "Harold S.",
               "phone" : "123-456-8888"
            },
            "items" : [
               {
                  "car" : "BMW X3 SUV",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693329091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "20",
            "amount" : 59800,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Newark",
                  "state" : "NJ"
               },
               "age" : 44,
               "credit_score" : 782,
               "name" : "Leslie E.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1705338691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19",
            "amount" : 46980,
            "customer" : {
               "address" : {
                  "address_line" : "5678 Elm St",
                  "city" : "Hartford",
                  "state" : "CT"
               },
               "age" : 20,
               "credit_score" : 698,
               "name" : "Vivian W.",
               "phone" : "123-456-1199"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1704215491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • customer.address.state: This property contains the customer’s state of residence.

        • $ne: This operator is used to compare for a not equal condition. In this example, "NY" is the value; meaning each document where the customer.address.state is not NY are returned. The filter applies to the customer, not the seller. And yes, the city of West New York is in New Jersey.

Find with $not to find documents that do not match the filter

The following JSON payload uses the $not logical operator to find purchased cars where purchase_type is not "In Person". In this example data, that means documents are returned where the car was purchased "Online".

The $not operator works when filtering on objects. It does not imply filtering on arrays in the searched documents. Notice in the example document that purchase_type is an object; it is not part of an array.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find": {
        "filter": {
            "$not": {
                "purchase_type": "In Person"
            }
        }
    }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.17,
               0.15,
               0.43,
               0.55
            ],
            "_id" : "18",
            "amount" : 106900,
            "customer" : {
               "address" : {
                  "address_line" : "98980 20th St",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 45,
               "credit_score" : 724,
               "name" : "Thomas D.",
               "phone" : "123-456-1188"
            },
            "items" : [
               {
                  "car" : "BMW 750e xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1703092291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.07
            ],
            "_id" : "13",
            "amount" : 55000,
            "customer" : {
               "address" : {
                  "address_line" : "1234 4th Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 60,
               "credit_score" : 702,
               "name" : "Aaron W.",
               "phone" : "123-456-1133"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1697389891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.06
            ],
            "_id" : "9",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "22345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 22,
               "credit_score" : 690,
               "name" : "Richard Z.",
               "phone" : "123-456-9999"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693588291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "7",
            "amount" : 61050,
            "customer" : {
               "address" : {
                  "address_line" : "22999 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 66,
               "credit_score" : 802,
               "name" : "Jeff G.",
               "phone" : "123-456-7777"
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1692119491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19",
            "amount" : 46980,
            "customer" : {
               "address" : {
                  "address_line" : "5678 Elm St",
                  "city" : "Hartford",
                  "state" : "CT"
               },
               "age" : 20,
               "credit_score" : 698,
               "name" : "Vivian W.",
               "phone" : "123-456-1199"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1704215491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • $not: This logical operator returns objects in documents that do not match the filter.

      • purchase_type: The object specified, in this example purchase_type whose value is "In Person".

Find with $nin where seller.location does not contain specified values

The following JSON payload uses the $nin (NOT IN) comparison operator to find documents where the seller.location does not contain "Manhattan NYC" or "Brooklyn NYC".

The $nin operator works when filtering on objects. It does not imply filtering on arrays in the searched documents. Notice in the example document that seller is an object; it is not part of an array.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find": {
        "filter": {
            "seller.location": {
                "$nin": ["Manhattan NYC","Brooklyn NYC"]
            }
        }
    }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10",
            "amount" : 93800,
            "customer" : {
               "address" : {
                  "address_line" : "9999 River Rd",
                  "city" : "Fair Haven",
                  "state" : "NJ"
               },
               "age" : 54,
               "credit_score" : 780,
               "name" : "Eric B.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Black"
               }
            ],
            "purchase_date" : {
               "$date" : 1694797891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8",
            "amount" : 46900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Orange",
                  "state" : "NJ"
               },
               "age" : 29,
               "credit_score" : 710,
               "name" : "Harold S.",
               "phone" : "123-456-8888"
            },
            "items" : [
               {
                  "car" : "BMW X3 SUV",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693329091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.33,
               0.44,
               0.55,
               0.77,
               0.66
            ],
            "_id" : "12",
            "amount" : 64900,
            "customer" : {
               "address" : {
                  "address_line" : "23 Main Blvd",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 55,
               "credit_score" : 786,
               "name" : "John T.",
               "phone" : "123-456-1123"
            },
            "items" : [
               {
                  "car" : "BMW 540i xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1696180291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "20",
            "amount" : 59800,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Newark",
                  "state" : "NJ"
               },
               "age" : 44,
               "credit_score" : 782,
               "name" : "Leslie E.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1705338691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.1,
               0.27
            ],
            "_id" : "6",
            "amount" : 109990,
            "customer" : {
               "address" : {
                  "address_line" : "32346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 43,
               "credit_score" : 764,
               "name" : "Chris E.",
               "phone" : "123-456-6666"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "Blue"
               }
            ],
            "purchase_date" : {
               "$date" : 1691860291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "16",
            "amount" : 58990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 38,
               "credit_score" : 700,
               "name" : "Tim C.",
               "phone" : "123-456-1166"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1701450691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • $nin: This comparison operator returns only the documents that are different from — that is, NOT IN — the documents matching the specified filter.

      • seller.location: This request returns documents where the seller.location does not contain "Manhattan NYC" or "Brooklyn NYC".

Find with range operators $gte and $lt

The following JSON payload uses the $gte and $lt operators (joined by $and) to find documents where the customers' credit scores are within a specified range.

The available range operators are $gt, $gte, $lt, and $lte. The available logical operators are $and, $or, and $not. The example that follows uses a subset of available operators. Try different operators with your data and apps to see the results.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "find": {
        "filter": {
            "$and": [
                {
                    "customer.credit_score": {
                        "$gte": 700
                    }
                },
                {
                    "customer.credit_score": {
                        "$lt": 800
                    }
                }
            ]
        }
    }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "21",
            "amount" : 65250,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Park Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 62,
               "credit_score" : 786,
               "name" : "Rachel I.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years",
               "Gap Insurance - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1706202691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10",
            "amount" : 93800,
            "customer" : {
               "address" : {
                  "address_line" : "9999 River Rd",
                  "city" : "Fair Haven",
                  "state" : "NJ"
               },
               "age" : 54,
               "credit_score" : 780,
               "name" : "Eric B.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Black"
               }
            ],
            "purchase_date" : {
               "$date" : 1694797891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8",
            "amount" : 46900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Orange",
                  "state" : "NJ"
               },
               "age" : 29,
               "credit_score" : 710,
               "name" : "Harold S.",
               "phone" : "123-456-8888"
            },
            "items" : [
               {
                  "car" : "BMW X3 SUV",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693329091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.21,
               0.27
            ],
            "_id" : "14",
            "amount" : 110400,
            "customer" : {
               "address" : {
                  "address_line" : "1414 14th Pl",
                  "city" : "Brooklyn",
                  "state" : "NY"
               },
               "age" : 44,
               "credit_score" : 702,
               "name" : "Kris S.",
               "phone" : "123-456-1144"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "White"
               }
            ],
            "purchase_date" : {
               "$date" : 1698513091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.17,
               0.15,
               0.43,
               0.55
            ],
            "_id" : "18",
            "amount" : 106900,
            "customer" : {
               "address" : {
                  "address_line" : "98980 20th St",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 45,
               "credit_score" : 724,
               "name" : "Thomas D.",
               "phone" : "123-456-1188"
            },
            "items" : [
               {
                  "car" : "BMW 750e xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1703092291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.33,
               0.44,
               0.55,
               0.77,
               0.66
            ],
            "_id" : "12",
            "amount" : 64900,
            "customer" : {
               "address" : {
                  "address_line" : "23 Main Blvd",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 55,
               "credit_score" : 786,
               "name" : "John T.",
               "phone" : "123-456-1123"
            },
            "items" : [
               {
                  "car" : "BMW 540i xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1696180291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "20",
            "amount" : 59800,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Newark",
                  "state" : "NJ"
               },
               "age" : 44,
               "credit_score" : 782,
               "name" : "Leslie E.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1705338691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.07
            ],
            "_id" : "13",
            "amount" : 55000,
            "customer" : {
               "address" : {
                  "address_line" : "1234 4th Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 60,
               "credit_score" : 702,
               "name" : "Aaron W.",
               "phone" : "123-456-1133"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1697389891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.1,
               0.27
            ],
            "_id" : "6",
            "amount" : 109990,
            "customer" : {
               "address" : {
                  "address_line" : "32346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 43,
               "credit_score" : 764,
               "name" : "Chris E.",
               "phone" : "123-456-6666"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "Blue"
               }
            ],
            "purchase_date" : {
               "$date" : 1691860291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "16",
            "amount" : 58990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 38,
               "credit_score" : 700,
               "name" : "Tim C.",
               "phone" : "123-456-1166"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1701450691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • $and is a logical operator that returns documents that match all of the specified conditions; in this example, the $gte and $lt range operators enclosed within the $and.

        • $gte and lt: These operators work together to return the documents for customers who have credit scores (at the time of purchase) in the specified range: greater than or equal to 700, and less than 800.

        • customer.credit_score: The property that contains each customer’s credit score.

Find with $size where items array has three items

The following JSON payload uses the $size query operator to find documents where the filtered array (items) has a size of 3.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "items": {
        "$size": 3
      }
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "21",
            "amount" : 65250,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Park Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 62,
               "credit_score" : 786,
               "name" : "Rachel I.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years",
               "Gap Insurance - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1706202691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.26
            ],
            "_id" : "4",
            "amount" : 48510,
            "customer" : {
               "address" : {
                  "address_line" : "12346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 40,
               "credit_score" : 802,
               "name" : "Lester M.",
               "phone" : "123-456-4444"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Red"
               },
               "Extended warranty - 5 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690909891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • items: This property is an array.

      • $size: This query operator specifying that the operation should match any document where the array property has a number of elements equal to the specified value.

      • 3: This value indicates the specific size requirement for the items array. In this case, the "find" operation looks for documents where the items array contains exactly three elements.

Find with $all where array has two given items

The following JSON payload uses the $all query operator to find all documents where the data has the given car & color (white Tesla Model Y), and an extended warranty of 5 years.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "items": {
        "$all": [
          {
            "car": "Tesla Model Y",
            "color": "White"
          },
          "Extended warranty - 5 years"
        ]
      }
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "16",
            "amount" : 58990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 38,
               "credit_score" : 700,
               "name" : "Tim C.",
               "phone" : "123-456-1166"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1701450691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • items: This property is an array.

      • $all: This query operator is used to match arrays that contain all elements specified in the query, regardless of order or other elements in the array. It requires that each element specified is a match.

        The array following $all specifies the elements that must all be present in the items array of the documents for a match to occur.

        The first element is an object representing an item with two properties: car with the value Tesla Model Y, and color with the value White. This indicates a requirement for an object in the items array with the same structure and values.

        The second element, Extended warranty - 5 years, represents a requirement for a string value in the items array that matches it exactly.

Find with $eq where array has only given data

The following JSON payload uses the $eq query operator to find all documents where the data has the given car & color (black BMW), and an extended warranty of 5 years, and gap insurance of 5 years.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "items": {
        "$eq": [
          {
            "car": "BMW M440i Gran Coupe",
            "color": "Silver"
          },
          "Extended warranty - 5 years",
          "Gap Insurance - 5 years"
        ]
      }
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "21",
            "amount" : 65250,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Park Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 62,
               "credit_score" : 786,
               "name" : "Rachel I.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years",
               "Gap Insurance - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1706202691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • items: This property is an array.

      • $eq: This is a query operator used to match values. It filters the documents to fetch only those where the specified property holds a value that is exactly equal to the specified value.

        The value for $eq is an array, indicating that this query is searching for documents where the items property is an array matching this exact array value. The array consists of:

        An object with car key having the value BMW, and color key with the value Black.

        A string value Extended warranty - 5 years.

        A string value Gap Insurance - 5 years.

Find pagination example to get first 20 documents on page 1

The following JSON payload is designed to find {} all documents in the collection and (for example purposes) return a nextPageState value so the we can demo in the next section the way to get the rest of the results on page 2.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.09
            ],
            "_id" : "17",
            "amount" : 54900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Hoboken",
                  "state" : "NJ"
               },
               "age" : 61,
               "credit_score" : 694,
               "name" : "Yolanda Z.",
               "phone" : "123-456-1177"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "Blue"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1702660291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.08
            ],
            "_id" : "15",
            "amount" : 52990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Maple Ave",
                  "city" : "West New York",
                  "state" : "NJ"
               },
               "age" : 41,
               "credit_score" : 782,
               "name" : "Maddy O.",
               "phone" : "123-456-1155"
            },
            "items" : {
               "car" : "Tesla Model 3",
               "color" : "White"
            },
            "purchase_date" : {
               "$date" : 1701191491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "21",
            "amount" : 65250,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Park Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 62,
               "credit_score" : 786,
               "name" : "Rachel I.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years",
               "Gap Insurance - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1706202691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.68
            ],
            "_id" : "10",
            "amount" : 93800,
            "customer" : {
               "address" : {
                  "address_line" : "9999 River Rd",
                  "city" : "Fair Haven",
                  "state" : "NJ"
               },
               "age" : 54,
               "credit_score" : 780,
               "name" : "Eric B.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Black"
               }
            ],
            "purchase_date" : {
               "$date" : 1694797891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.3,
               0.23,
               0.15,
               0.17,
               0.4
            ],
            "_id" : "8",
            "amount" : 46900,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Orange",
                  "state" : "NJ"
               },
               "age" : 29,
               "credit_score" : 710,
               "name" : "Harold S.",
               "phone" : "123-456-8888"
            },
            "items" : [
               {
                  "car" : "BMW X3 SUV",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693329091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.21,
               0.27
            ],
            "_id" : "14",
            "amount" : 110400,
            "customer" : {
               "address" : {
                  "address_line" : "1414 14th Pl",
                  "city" : "Brooklyn",
                  "state" : "NY"
               },
               "age" : 44,
               "credit_score" : 702,
               "name" : "Kris S.",
               "phone" : "123-456-1144"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "White"
               }
            ],
            "purchase_date" : {
               "$date" : 1698513091
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "11",
            "amount" : 57500,
            "customer" : {
               "address" : {
                  "address_line" : "99 Elm St",
                  "city" : "Fair Lawn",
                  "state" : "NJ"
               },
               "age" : 47,
               "credit_score" : 660,
               "name" : "Ann J.",
               "phone" : "123-456-1112"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1695921091
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.15,
               0.17,
               0.15,
               0.43,
               0.55
            ],
            "_id" : "18",
            "amount" : 106900,
            "customer" : {
               "address" : {
                  "address_line" : "98980 20th St",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 45,
               "credit_score" : 724,
               "name" : "Thomas D.",
               "phone" : "123-456-1188"
            },
            "items" : [
               {
                  "car" : "BMW 750e xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1703092291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.33,
               0.44,
               0.55,
               0.77,
               0.66
            ],
            "_id" : "12",
            "amount" : 64900,
            "customer" : {
               "address" : {
                  "address_line" : "23 Main Blvd",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 55,
               "credit_score" : 786,
               "name" : "John T.",
               "phone" : "123-456-1123"
            },
            "items" : [
               {
                  "car" : "BMW 540i xDrive Sedan",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1696180291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "20",
            "amount" : 59800,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Newark",
                  "state" : "NJ"
               },
               "age" : 44,
               "credit_score" : 782,
               "name" : "Leslie E.",
               "phone" : null
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1705338691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.25
            ],
            "_id" : "1",
            "amount" : 47601,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 51,
               "credit_score" : 782,
               "name" : "Jim A.",
               "phone" : "123-456-1111"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Silver"
               },
               "Extended warranty - 5 years"
            ],
            "preferred_customer" : true,
            "purchase_date" : {
               "$date" : 1690045891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.07
            ],
            "_id" : "13",
            "amount" : 55000,
            "customer" : {
               "address" : {
                  "address_line" : "1234 4th Ave",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 60,
               "credit_score" : 702,
               "name" : "Aaron W.",
               "phone" : "123-456-1133"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1697389891
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.06
            ],
            "_id" : "9",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "22345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 22,
               "credit_score" : 690,
               "name" : "Richard Z.",
               "phone" : "123-456-9999"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1693588291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.045,
               0.38,
               0.31,
               0.67
            ],
            "_id" : "5",
            "amount" : 94990,
            "customer" : {
               "address" : {
                  "address_line" : "32345 Main Ave",
                  "city" : "Jersey City",
                  "state" : "NJ"
               },
               "age" : 50,
               "credit_score" : 800,
               "name" : "David C.",
               "phone" : "123-456-5555"
            },
            "items" : [
               {
                  "car" : "Tesla Model S",
                  "color" : "Red"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690996291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.11,
               0.02,
               0.78,
               0.1,
               0.27
            ],
            "_id" : "6",
            "amount" : 109990,
            "customer" : {
               "address" : {
                  "address_line" : "32346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 43,
               "credit_score" : 764,
               "name" : "Chris E.",
               "phone" : "123-456-6666"
            },
            "items" : [
               {
                  "car" : "Tesla Model X",
                  "color" : "Blue"
               }
            ],
            "purchase_date" : {
               "$date" : 1691860291
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Jersey City NJ",
               "name" : "Jim A."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.21,
               0.22,
               0.33,
               0.44,
               0.53
            ],
            "_id" : "7",
            "amount" : 61050,
            "customer" : {
               "address" : {
                  "address_line" : "22999 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 66,
               "credit_score" : 802,
               "name" : "Jeff G.",
               "phone" : "123-456-7777"
            },
            "items" : [
               {
                  "car" : "BMW M440i Gran Coupe",
                  "color" : "Black"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1692119491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.44,
               0.11,
               0.33,
               0.22,
               0.88
            ],
            "_id" : "16",
            "amount" : 58990,
            "customer" : {
               "address" : {
                  "address_line" : "1234 Main St",
                  "city" : "Staten Island",
                  "state" : "NY"
               },
               "age" : 38,
               "credit_score" : 700,
               "name" : "Tim C.",
               "phone" : "123-456-1166"
            },
            "items" : [
               {
                  "car" : "Tesla Model Y",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1701450691
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.27
            ],
            "_id" : "19",
            "amount" : 46980,
            "customer" : {
               "address" : {
                  "address_line" : "5678 Elm St",
                  "city" : "Hartford",
                  "state" : "CT"
               },
               "age" : 20,
               "credit_score" : 698,
               "name" : "Vivian W.",
               "phone" : "123-456-1199"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "White"
               },
               "Extended warranty - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1704215491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.1,
               0.15,
               0.3,
               0.12,
               0.05
            ],
            "_id" : "2",
            "amount" : 53990,
            "customer" : {
               "address" : {
                  "address_line" : "888 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 34,
               "credit_score" : 700,
               "name" : "Jack B.",
               "phone" : "123-456-2222"
            },
            "items" : [
               {
                  "car" : "Tesla Model 3",
                  "color" : "White"
               },
               "Extended warranty - 10 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690391491
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Staten Island NYC",
               "name" : "Tammy S."
            },
            "status" : "active"
         },
         {
            "$vector" : [
               0.25,
               0.25,
               0.25,
               0.25,
               0.26
            ],
            "_id" : "4",
            "amount" : 48510,
            "customer" : {
               "address" : {
                  "address_line" : "12346 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 40,
               "credit_score" : 802,
               "name" : "Lester M.",
               "phone" : "123-456-4444"
            },
            "items" : [
               {
                  "car" : "BMW 330i Sedan",
                  "color" : "Red"
               },
               "Extended warranty - 5 years",
               "Service - 5 years"
            ],
            "purchase_date" : {
               "$date" : 1690909891
            },
            "purchase_type" : "In Person",
            "seller" : {
               "location" : "Manhattan NYC",
               "name" : "Jon B."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : "CgAAAAEBAAAAATQA8H///+sA"
   }
}

About the key-value pair:

  • find: This find {} command selects and returns all documents from the collection.

  • The find command is used here — for pagination example purposes — to return a nextPageState value, so we can show in the next section how to retrieve the rest of the results on a subsequent page.

Find pagination example to get more documents on page 2

The following JSON payload is designed to find page 2 of results based on the computed nextPageState cursor (see the prior section), which you would then specify on the pageState clause of this follow-on command. Your nextPageState cursor value may vary from the prior example and here in pageState.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "options" : {"pageState" : "CgAAAAEBAAAAATQA8H///+sA"}
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "$vector" : [
               0.15,
               0.1,
               0.1,
               0.35,
               0.55
            ],
            "_id" : "3",
            "amount" : 4600,
            "customer" : {
               "address" : {
                  "address_line" : "12345 Broadway",
                  "city" : "New York",
                  "state" : "NY"
               },
               "age" : 30,
               "credit_score" : 742,
               "name" : "Jill D.",
               "phone" : "123-456-3333"
            },
            "items" : "Extended warranty - 10 years",
            "purchase_date" : {
               "$date" : 1690564291
            },
            "purchase_type" : "Online",
            "seller" : {
               "location" : "Brooklyn NYC",
               "name" : "Jasmine S."
            },
            "status" : "active"
         }
      ],
      "nextPageState" : null
   }
}

About the command and each key-value pair:

  • find: In this example, the command uses options to determine how the results (documents) should be returned from the collection. This command uses and returns documents from a collection based on specified criteria.

    • options: This clause contains one or more optional parameters to alter the behavior of the find command. These are not conditions for selecting documents. Instead, the options are settings for how the query should be executed or how the results should be returned. In this example, just one option is presented.

      • pageState: This key specifies a particular state of pagination in the query’s result set. The example value CgAAAAEBAAAAATQA8H///+sA is an encoded string that represents a specific point or cursor in a set of paginated data.

        The presence of the pageState indicates that the Data API is capable of paginated reads from the database. It’s a feature for handling large sets of data. Instead of returning all documents at once, the data is returned in subsets (pages), and the pageState is a cursor that points to a specific position within this dataset, indicating where the next page of data should begin.

Find and update data

This section provides examples of Data API commands that find and update, replace, or delete data — while using a variety of options clauses:

  • findOneAndUpdate

  • findOneAndReplace

  • findOneAndDelete

Find one and update with $sort and $set for active status

The following JSON payload uses the $sort and $set operators to update the status of one matching document (per $vector) as active. In this case, notice that the response returns a modifiedCount of 0 because the matching document’s status was already active.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "findOneAndUpdate": {
        "sort": {
            "$vector": [
                0.25,
                0.045,
                0.38,
                0.31,
                0.67
            ]
        },
        "update": {
            "$set": {
                "status": "active"
            }
        },
        "options": {
            "returnDocument": "after"
        }
    }
}' | json_pp
{
    "data": {
        "document": {
            "_id": "5",
            "purchase_type": "Online",
            "$vector": [
                0.25,
                0.045,
                0.38,
                0.31,
                0.67
            ],
            "customer": {
                "name": "David C.",
                "phone": "123-456-5555",
                "age": 50,
                "credit_score": 800,
                "address": {
                    "address_line": "32345 Main Ave",
                    "city": "Jersey City",
                    "state": "NJ"
                }
            },
            "purchase_date": {
                "$date": 1690996291
            },
            "seller": {
                "name": "Jim A.",
                "location": "Jersey City NJ"
            },
            "items": [
                {
                    "car": "Tesla Model S",
                    "color": "Red"
                },
                "Extended warranty - 5 years"
            ],
            "amount": 94990,
            "status": "active"
        }
    },
    "status": {
        "matchedCount": 1,
        "modifiedCount": 0
    }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command aims to find one document based on certain criteria and then update that document.

    • sort: This clause contains an object specifying the sort criteria for selecting the document.

    • $vector: This indicates a vector-based sort operation, where the documents are sorted based on the provided vector values. In this example, [0.15, 0.1, 0.1, 0.35, 0.55].

    • update: Contains the changes to be applied to the selected document.

      • $set: This is an update operator used to set the value of a field. Here, it is used to set the status property of the document to active. In this case, though, notice that the response returns a modifiedCount of 0 because the matching document’s status was already active.

      • options: Provides additional settings for the findOneAndUpdate command.

        • returnDocument: after`: This option specifies that the modified document should be returned in the response after the update is applied. This allows the client to see the updated state of the document immediately.

In summary, this JSON payload instructs the server to perform a findOneAndUpdate command on the vector-enabled Astra DB Serverless database. It should find the document sorted according to the specified vector values, update the status property of this document to active (if not already that value), and return the updated document in the response.

Find one and update with $set to set values in tags array

The following JSON payload uses the $set update operator to set values in a tags array with multiple data types. Also, the options include an upsert operation.

Using the upsert option

Before running the curl example, let’s say more about the upsert option. The term "upsert" is a combination of "update" and "insert." It’s a common concept in database operations. When you perform an upsert, you are telling the database to update a particular record if it exists, or insert it as a new record if it doesn’t.

The upsert boolean, when set to true, enables this behavior. When you set upsert to false, you are instructing the database to only update the existing record and not to insert a new record if a matching record doesn’t exist. Here’s how it works in both scenarios:

  • "upsert" : true

    • If the record exists: The database updates the existing record.

    • If the record does not exist: The database creates a new record with the provided data.

  • "upsert" : false (or if the upsert option is omitted, as false is the default

    • If the record exists: The database updates the existing record.

    • If the record does not exist: No action is taken; no new record is created.

Use this upsert option in apps where you need to ensure you’re not creating duplicate records but still updating existing ones, as needed.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id",
      "amount": 65,
      "wait" : 42
    },
    "update" : {"$set" : { "tags" : ["my test", 5, true, null], "min_col": 2, "max_col": 99}},
    "options" : {"returnDocument" : "after", "upsert" : true}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "amount" : 65,
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "my test",
            5,
            true,
            null
         ],
         "wait" : 42
      }
   },
   "status" : {
      "matchedCount" : 0,
      "modifiedCount" : 0,
      "upsertedId" : "upsert-id"
   }
}

About the command and each key-value pair:

  • find: This command selects and returns documents from a collection based on specified criteria.

    • filter: A nested object within find indicating the conditions or parameters used to select the documents.

      • "_id": "upsert-id": Targets a document with an identifier (_id) equal to upsert-id.

        • "amount": 65: The document must have an amount property with the value 65.

        • "wait" : 42: The document must also have a wait property with the value 42.

      • update: This key holds an object defining what updates are applied to the found document. It uses the $set update operator to specify the new values for the fields:

        "tags" : ["my test", 5, true, null]: The tags property is set to this array of various data types.

        "min_col": 2, "max_col": 99: The min_col and max_col properties are set to 2 and 99, respectively.

      • options: This key is associated with an object that contains additional settings for the findOneAndUpdate command:

        "returnDocument" : "after": This option specifies that the updated document should be returned after the changes have been applied. The alternative is usually "before", which would return the document as it was before the update.

        "upsert" : true: This important option specifies that if no document matches the provided filter criteria, a new document should be created with the specified update parameters and any filter parameters that are valid fields.

In essence, this JSON payload is instructing the server to find a document in the database that meets certain criteria and update specific properties in that document. Additionally, it specifies that if no matching document is found, a new one should be created using the provided data (upsert operation), and the version of the document returned should be the one that includes the applied updates.

Find one and update with $unset to unset an amount from a matching document

The following JSON payload is designed to perform a findOneAndUpdate with the $unset update operator to unset (remove) the amount property from the matching document.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : {"$unset" : {"amount": ""}},
    "options" : {"returnDocument" : "after"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "my test",
            5,
            true,
            null
         ],
         "wait" : 42
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": The criterion that the document must have an identifier (_id) equal to upsert-id.

    • update: This key holds an object indicating the changes to be applied to the selected document. It uses the $unset update operator.

      • "$unset" : {"amount": ""}: The $unset update operator is used to delete a particular field. Here, it’s specified to remove the amount property from the document. The value is an empty string, which is the standard way to indicate removal regardless of the property’s current value.

      • options: This key is paired with an object that dictates additional settings for the findOneAndUpdate command:

        "returnDocument" : "after": This setting dictates that the response should consist of the document after the update has been applied. This means the returned document reflects the changes made, which, in this case, is the removal of the amount field.

Summary: This Data API payload is a command to the server to locate a document with the ID upsert-id and remove the amount property from it. The command example returns the document after the amount property has been removed, allowing the requestor to see the immediate result of the update.

Find one and update with $inc to decrement a wait list by 1

The following JSON payload uses the $inc option to decrement a wait list by 1.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : {"$inc" : {"wait": -1}},
    "options" : {"returnDocument" : "after", "upsert" : false}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "my test",
            5,
            true,
            null
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$inc" : {"wait": -1}: The $inc operator is used to increment a property by a certain value. Here, it is specified to increment the wait property by -1, which effectively decrements the property’s current value by 1.

    • options: Holds additional settings for the findOneAndUpdate command:

      • "returnDocument" : "after": This option specifies that the operation should return the modified document as it appears after the update. It allows the requester to immediately see the changes made, which, in this case, is the decrement of the wait field.

      • "upsert" : false": The upsert option, when true, would create a new document in the database if no documents match the filter criteria. By setting it to false, this operation specifies that no new document should be created if none match the _id specified in the filter.

In essence, this JSON payload is instructing the server to find a document with the ID upsert-id and decrease the value of the wait property by 1. The operation returns the document with the updated wait property and does not create a new document if upsert-id doesn’t match any existing document.

Find one and update using $push to add data to tags array

The following JSON payload uses the $push update operator to add data in the "tags" array. Notice in the response that "High priority" has been added, by default to the end of the array.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$push": { "tags": "High priority" }},
    "options" : {"returnDocument" : "after"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "my test",
            5,
            true,
            null,
            "High priority"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$push": { "tags": "High priority" }: The $push operator is used to add a new value to an array property within a document. Here, it’s instructed to add the string High priority to the tags array of the document.

    • options: Contains additional settings for the operation:

      • "returnDocument" : "after": This setting indicates that the response should contain the document as it appears after the update. It allows the client to see the document with the newly added High priority tag in the tags property immediately after the operation.

Summary: This Data API command tells the server to find a document with the ID upsert-id and add the string High priority to the tags property of that document. The operation is set to return the updated document after the change has been applied, allowing the requester to see the updated tags field.

Find one and update using $pop to remove last data in tags array

The following JSON payload uses the $pop update operator to remove the last data in the "tags" array. Notice in the response that "High priority" is now removed. It was the last value in the tags array that was added by the prior command.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$pop": { "tags": 1 }},
    "options" : {"returnDocument" : "after"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "my test",
            5,
            true,
            null
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$pop": { "tags": 1 }: The $pop operator is used to remove the last element from an array property in a document if the value is 1, or the first if the value is -1. Here, it’s instructed to remove the last element from the tags array.

    • options: Defines additional settings for the command.

      • "returnDocument" : "after": This option requests that the response should include the document as it exists after the update has been applied. This allows the requester to view the final state of the tags array, reflecting the removal of its last element.

Summary: This Data API command is instructing the server to find a document with the ID upsert-id and perform an operation to remove the last element from the tags array in that document. It is further requested that the operation’s response should return the document in its updated state post-operation, enabling the requester to immediately see the effect of the $pop operation on the tags array.

Find one and update to add multiple elements to tags array

The following JSON payload uses the $push and $each update operators to add new entries named "last-1" and "last" at the end of the "tags" array; the action occurs only for matching documents that have the "upsert-id" value for _id.

The options in this example declare that upsert is false. In effect, we are instructing the database to only update the existing document, and not to insert a new document if a matching document doesn’t exist. To reiterate, when upsert is false:

  • If the document exists: The database updates the existing document.

  • If the document does not exist: No action is taken; no new document is created.

For more, see the upsert summary in this section.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$push": { "tags": { "$each": [ "last-1", "last"] } } },
    "options" : {"returnDocument" : "after", "upsert" : false}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "my test",
            5,
            true,
            null,
            "last-1",
            "last"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$push": { "tags": { "$each": [ "last-1", "last"] } }: The $push operator is used to add one or more items to an array. If the $each modifier is provided, all elements in the array specified by $each are added to the tags array in the document. Here, it’s instructed to add the strings last-1 and last to the tags array of the document.

    • options: Additional settings that affect the command.

      • "returnDocument": "after": This setting dictates that the operation’s response should include the document as it appears after the update operation has been applied, rather than the document as it appeared beforehand.

      • "upsert": false: This indicates that if a document matching the filter conditions is not found, the operation should not create a new document (which would happen if this were set to true).

Summary: This Data API command is instructing the server to identify a document with the ID upsert-id and append the values last-1 and last to the tags array within that document. The command is configured not to create a new document if a matching document is not found, and the response is expected to show the state of the document after the update has been made.

Find one and update adding element to starting position in tags array

The following JSON payload uses the $push, $each, and $position update operators to add new entries named "first" and "second" in the "tags" array, at the top of the array; the action occurs only for matching documents that have the "upsert-id" value for _id.

The options in this example declare that upsert is false. In effect, we are instructing the database to only update the existing document, and not to insert a new document if a matching document doesn’t exist. To reiterate, when upsert is false:

  • If the document exists: The database updates the existing document.

  • If the document does not exist: No action is taken; no new document is created.

For more, see the upsert summary in this section.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$push": { "tags" : { "$each": [ "first", "second" ] ,
           "$position" : 0 } } },
    "options" : {"returnDocument" : "after", "upsert" : false}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "first",
            "second",
            "my test",
            5,
            true,
            null,
            "last-1",
            "last"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$push": { "tags" : { "$each": [ "first", "second" ], "$position" : 0 } }: This is an instruction to add new elements to an array property within the selected document. The $push operator is used to append the elements to the tags array.

      • "$each": [ "first", "second" ]: This modifier allows multiple values to be appended to the array. Here, the strings first and second are to be added.

      • "$position" : 0: This modifier specifies the position in the array where the new elements should be added. The value 0 indicates that the elements should be inserted at the beginning of the tags array, rather than the end (which is the default behavior for $push).

    • options: These are additional parameters that control the behavior of the operation.

      • "returnDocument": "after": When set to after this option indicates that the response should contain the document in its state after the update has been applied (as opposed to its state before the update).

      • "upsert": false": This boolean indicates whether a new document should be created if no document matches the filter criteria. The value false means no new document should be created (an upsert operation should not occur).

Summary: This Data API command tells the server to find a document with an ID of upsert-id and add the strings first and second to the start of the tags array within that document. The command should not create a new document if no matching document is found, and the response should reflect the document’s state after the modifications have been made.

Find one and update with $max and $min values (if conditions are met)

The following JSON payload uses the $max and $min operators with findOneAndUpdate to perform the following updates: set the max_col value to 25 if the existing value is less than 25; and set the min_col value to 5 if the existing value is greater than 5.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$max": { "max_col" : 25 }, "$min" : {"min_col" : 5} },
    "options" : {"returnDocument" : "after"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 99,
         "min_col" : 2,
         "tags" : [
            "first",
            "second",
            "my test",
            5,
            true,
            null,
            "last-1",
            "last"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 0
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$max": { "max_col" : 25 }: This clause sets the value of the property max_col to 25 if it’s currently lower; if the existing value is higher, no change is made. The $max operator only updates the field if the specified value is higher than the current one.

      • "$min" : {"min_col" : 5}: Conversely, this operation sets the value of the property min_col to 5 if it’s currently higher; if the existing value is lower, no change is made. The $min operator only updates the field if the specified value is lower than the existing one.

    • options: Specifies additional settings that control how the findOneAndUpdate command should be executed.

      • "returnDocument" : "after": This option dictates that the Data API should return the document as it appears after the update has been applied, rather than what it looked like before the update.

Summary: This Data API command is instructing the database to find a document with the identifier upsert-id' and perform the following updates: set the `max_col value to 25 if the existing value is less than 25; and set the min_col value to 5 if the existing value is greater than 5. The command is configured to return the document after these updates have been applied.

Find one and update with $max and $min values (conditions are met)

The following JSON payload uses the $max and $min update operators to update $max and $min values. In this example with the sample data, the conditions are met.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$max": { "max_col" : 100 }, "$min" : {"min_col" : 1} },
    "options" : {"returnDocument" : "after"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 100,
         "min_col" : 1,
         "tags" : [
            "first",
            "second",
            "my test",
            5,
            true,
            null,
            "last-1",
            "last"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$max": { "max_col" : 100 }: This clause sets the value of the property max_col to 100 if it’s currently lower; if the existing value is higher, no change is made. The $max operator only updates the field if the specified value is higher than the current one.

      • "$min" : {"min_col" : 1}: Conversely, this operation sets the value of the property min_col to 1 if it’s currently higher; if the existing value is lower, no change is made. The $min operator only updates the field if the specified value is lower than the existing one.

    • options: Specifies additional settings that control how the findOneAndUpdate command should be executed.

      • "returnDocument" : "after": This option dictates that the Data API should return the document as it appears after the update has been applied, rather than what it looked like before the update.

Summary: This Data API command is instructing the database to find a document with the identifier upsert-id' and perform the following updates: set the `max_col value to 100 if the existing value is less than 100 (yes: it was previously set to 99); and set the min_col value to 1 if the existing value is greater than 1 (yes: it was previously set to 2). The command is configured to return the document after these updates have been applied.

Find one and update with $addToSet

The following JSON payload uses the $addToSet operation to add data to an array if the value is not already present. Notice in this example the value was already present; thus the response contains "modifiedCount" : 0.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$addToSet": { "tags" : "first" }},
    "options" : {"returnDocument" : "after"}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "max_col" : 100,
         "min_col" : 1,
         "tags" : [
            "first",
            "second",
            "my test",
            5,
            true,
            null,
            "last-1",
            "last"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 0
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$addToSet": { "tags" : "first" }: The $addToSet operator adds a value to an array within the document only if the value does not already exist. In this case, it adds the value first to the tags array if "first" is not already an element in the array.

    • options: Dictates additional settings for the findOneAndUpdate command.

      • "returnDocument" : "after": This option specifies that the response from the command should be the document as it appears post-update, rather than the pre-update version.

The $addToSet operator is used this way when having a unique list of values is important, avoiding duplicates in an array property within a database collection’s document.

Summary: This Data API command is designed to instruct the database to identify a document with the identifier upsert-id and add the string first to the tags array within the document, assuming first is not already present. The operation then returns the updated document as the response.

Find one and update with $rename

The following JSON payload uses the $rename update operator to give new names to two fields, if those property names were found.

The options in this example declare that upsert is false. In effect, we are instructing the database to only update the existing document, and not to insert a new document if a matching document doesn’t exist. To reiterate, when upsert is false:

  • If the document exists: The database updates the existing document.

  • If the document does not exist: No action is taken; no new document is created.

For more, see the upsert summary in this section.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findOneAndUpdate": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : { "$rename": { "min_col" : "minimum", "max_col" : "maximum" } },
    "options" : {"returnDocument" : "after", "upsert" : false}
  }
}' | json_pp
{
   "data" : {
      "document" : {
         "_id" : "upsert-id",
         "maximum" : 100,
         "minimum" : 1,
         "tags" : [
            "first",
            "second",
            "my test",
            5,
            true,
            null,
            "last-1",
            "last"
         ],
         "wait" : 41
      }
   },
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • findOneAndUpdate: This command finds a single document based on the provided criteria (the filter) and then applies an update to that document.

    • filter: This clause contains an object specifying the criteria to select the document.

      • "_id": "upsert-id": This is the condition that the document must satisfy for it to be selected. It should have an identifier (_id) equal to upsert-id.

    • update: Contains the modifications to be made on the document.

      • "$rename": { "min_col" : "minimum", "max_col" : "maximum" }: The $rename operator is used to change the property names within a document. Here, it’s instructed to rename the property min_col to minimum, and max_col to maximum in the targeted document.

    • options: This key specifies additional settings for the findOneAndUpdate command.

      • returnDocument" : "after": This setting asks the system to return the modified document after the update is applied, as opposed to before the update.

      • "upsert" : false: This setting dictates that if a document matching the filter criteria is not found, no action is taken. Specifically, no new document is created (as would happen with "upsert": true).

Summary: This JSON payload is structured to command the database to find a document with the _id (upsert-id) and rename the properties min_col and max_col to minimum and maximum, respectively, in that document. The operation is configured not to create a new document if a matching document isn’t found, and it returns the document with the applied changes. This sort of operation is typical in scenarios where the property names in the documents are being refactored or standardized without altering their respective values.

Update data

This section provides examples of Data API commands that update data:

  • updateOne

  • updateMany

Use updateOne and $set to change dot notation property’s value

The following JSON payload uses the $set update operator to set the value of a property (which uses the dot notation customer.name) to a new value.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "updateOne": {
    "filter": {
      "_id": "upsert-id"
    },
    "update" : {"$set" : { "customer.name" : "CUSTOMER 22"}}
  }
}' | json_pp
{
   "status" : {
      "matchedCount" : 1,
      "modifiedCount" : 1
   }
}

About the command and each key-value pair:

  • updateOne: This command updates a single document that matches the given criteria within a database collection.

    • filter: This clause is used to select the document to be updated.

      • _id: This key within the filter object targets a unique identifier property in the database’s documents. The accompanying value upsert-id is the specific ID the API looks for when determining which document to update.

      • update: This key specifies what updates are applied to the document that meets the filter criteria. It’s an object that contains database update operators and the modifications they perform.

        • $set: This is an update operator that set the value of a property in a document.

        • customer.name: This notation is a nested document or a property within the main document, and name is a property within customer. The operation targets this nested field.

        • CUSTOMER 22: This value is what the customer.name property is updated to during the operation.

Use find to verify prior updateOne that used dot notation

The following JSON payload is designed to verify that the updateOne command from the prior example was completed.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "find": {
    "filter": {
      "_id": "upsert-id"
    }
  }
}' | json_pp
{
   "data" : {
      "documents" : [
         {
            "_id" : "upsert-id",
            "customer" : {
               "name" : "CUSTOMER 22"
            },
            "maximum" : 100,
            "minimum" : 1,
            "tags" : [
               "first",
               "second",
               "my test",
               5,
               true,
               null,
               "last-1",
               "last"
            ],
            "wait" : 41
         }
      ],
      "nextPageState" : null
   }
}

About the request:

  • find: This command searches for and retrieves documents from a collection.

    • filter: This clause holds an object that specifies the criteria for selecting documents in the database.

      • _id: A common convention represents a property in the documents that stores a unique identifier for each document. The corresponding value upsert-id is the specific ID the operation is intended to match.

About each key-value pair in the response:

  • data: This is the root object that contains the response data.

    • documents: An array containing the set of documents that matched the criteria specified in the original POST request. In this instance, it includes one document.

      • _id: This property holds the unique identifier for the document, and its value is upsert-id.

      • customer: An object containing data about a customer. In this case, it has one property:

        • name: The name of the customer, CUSTOMER 22.

      • maximum and minimum: These properties hold integer values that could represent thresholds or limits applicable to this document; their specific meanings depend on the application context.

      • tags: An array containing various types of values, including strings, a number, a boolean, and a null value. These tags might be used for categorizing, searching, or filtering purposes.

      • wait: An integer that could signify a duration or delay, although its specific purpose is dependent on the application context.

      • nextPageState: Used for pagination when you have more data to fetch than can be delivered in a single response. The value null indicates that there are no more pages to retrieve. That is, this response contains the last page, or the only set of results.

Update many matching documents with $set

The following JSON payload uses the $set update operator to set the status as "inactive" for those documents that had an "active" status before the update transaction.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "updateMany": {
    "filter": {"status" : "active" },
    "update" : {"$set" : { "status" : "inactive"}}
  }
}' | json_pp
{
   "status" : {
      "matchedCount" : 20,
      "modifiedCount" : 20,
      "moreData" : true
   }
}

About the command and each key-value pair:

  • updateMany: This command updates multiple documents in the database’s collection.

    • filter: This is an object that defines the criteria for selecting documents to which the command applies. The filter looks for documents where:

      • status: The key being evaluated in each document; a property within the documents in the database.

      • active: The value that the status property must match for the document to be selected. In this case, it’s targeting documents that currently have a status of active.

    • update: This is an object that specifies the modifications to be applied to all documents that match the criteria set by the filter.

      • $set: This is an update operator indicating that the operation should overwrite the value of a property (or properties) in the selected documents.

      • status: Specifies the property in the document to update.

      • inactive: The new value that the status property is set to for all selected documents. In this context, it’s changing the status from active to inactive.

Summary: This JSON command is instructing the database to update all documents where the status property is active, setting the status property to inactive. It’s a bulk update operation, as it potentially affects many documents that match the specified filter criteria.

Delete data

This section provides examples of Data API commands that delete data:

  • deleteOne

  • deleteMany

Delete one filtered by tags value

The deleteOne command deletes a single document. In this example, the deletion would occur where the tags value is first.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "deleteOne": {
    "filter": {
      "tags": "first"
    }
  }
}' | json_pp
{
   "status" : {
      "deletedCount" : 1
   }
}

About the command and each key-value pair:

  • The deleteOne command deletes a single document from a collection in the database. It’s designed to remove the first document that matches the provided criteria. If no matching document is found, no action is taken.

    • filter: This clause is nested within the deleteOne command and provides the conditions that the database uses to identify the document meant for deletion.

      • tags: The tags key, nested within the filter targets a specific property in the database’s documents.

      • first: This value is associated with the tags key, which must contain the string "first" to meet the deletion criteria.

Delete many filtered by status

The following JSON payload is designed to delete documents where the status is inactive.

The JSON structure is sent via an HTTP POST request to a server within an authenticated vector-enabled Astra DB Serverless database. Via the environment variables, the keyspace name is default_keyspace; and the collection name in this example is vector_collection.

If used with an empty { } filter or an empty body, the deleteMany command deletes all the data in your connected database’s collection. Use with caution! Example of the command with an empty body:

{
  "deleteMany": {
  }
}

Note that this command, with an empty filter or body, bypasses the guardrail of up to 20 rows deleted per transaction. Also, recall that the auth token is associated with the privileged Database Administrator role. If all data is removed in a collection, the response contains deletedCount: -1 (meaning all rows).

Example:

  • curl /api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION}

  • Result

curl -s --location \
--request POST ${ASTRA_DB_API_ENDPOINT}/api/json/v1/${ASTRA_DB_KEYSPACE}/${ASTRA_DB_COLLECTION} \
--header "Token: ${ASTRA_DB_APPLICATION_TOKEN}" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "deleteMany": {
    "filter": {
      "status": "inactive"
    }
  }
}' | json_pp
{
   "status" : {
      "deletedCount" : 20
   }
}

About the command and each key-value pair:

  • The deleteMany command deletes all matching documents from a collection based on the provided filter criteria.

    • filter: This clause is nested within the deleteMany command and provides the conditions that the database uses to identify one or more document(s) meant for deletion.

      • status: The status key used for filtering to decide which documents may be deleted.

        As noted, if used with an empty { } filter or an empty body, the deleteMany command deletes all the data in your database collection. Use with caution! Recall that the auth token is associated with the privileged Database Administrator role. If all data is removed in a collection, the response contains deletedCount: -1 (meaning all rows).

      • inactive: This value is associated with the status key, which in this example must contain the string "inactive" to meet the deletion criteria.

Delete a collection (reminder)

If you need to delete the entire collection, see the deleteCollection example that’s provided earlier in this topic.

What’s next?

If you haven’t already, see Data API with MongooseJS.

If you’re new to vector databases and vector search technology, see:

Also see:

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com