Developing with JSON API

In this public preview release, you can use the JSON API to develop AI applications that interact with Astra DB Vector databases, including operations that perform vector similarity searches.

To participate in this JSON API public preview release, sign into Astra Portal and create an Astra DB Vector database. Follow the instructions on the Connect tab and in this JSON API documentation.

At this time, the JSON API is for development environments only. Do not use this API in production. For more, see the DataStax Preview Terms.

For JavaScript developers, a simple setDriver configuration change to existing Node.js apps that use the popular Mongoose library lets you declare an Astra DB Vector database as your backend.

If you haven’t already, follow the introductory steps in the JSON API QuickStart with Mongoose.

You can submit JSON API operations directly via:

curl commands that send requests to your Astra DB Vector database, as featured in this topic’s reference examples.
The Swagger UI that you can launch from your vector database’s Connect tab in Astra Portal. The Swagger UI provides a "Try It Out" feature. The Swagger UI for JSON API is available at:

https://<db-id>-<region>.apps.astra.datastax.com/api/json/swagger-ui/
Postman collections in our public workspace:
- JSON API with Astra DB Vector Search
- JSON API non-vector

JSON API availability

The JSON API is available on all Astra DB Vector databases, for all cloud providers — AWS, Azure, or Google Cloud — and all supported regions listed (per cloud provider) in Astra Portal.
The JSON API is not available on Astra DB Serverless or Astra DB Classic databases.

The new JSON API may replace the Document API. In your development environment, we encourage you to use the JSON API with Astra DB Vector databases, instead of the Document API.

Supported Mongoose functionality

The JSON API supports most Mongoose functionality.

For details, refer to the stargate mongoose API reference in the GitHub repo for a comprehensive list of our supported Mongoose API functionality.

JSON API guardrails and limits

The JSON API include guardrails and sets limits to ensure best practices, foster availability, and promote optimal configurations for your databases.

Entity	Default	Maximum	Notes
Number of collections per namespace	n/a	5	Up to 5 collections in a namespace, which is known as a keyspace in Astra DB.
Number of indexes per keyspace	n/a	5	JSON API uses Storage Attached Indexing (SAI), and each Astra DB Vector database limits the number of SAI indexes in a keyspace to 5.
Page size	20	500	Document page size.
Sort page size	100	500	Document page size for sorting; implemented as separate from page size because sort operations need more rows per page.
Maximum document sort count	10000	10000	Maximum limit of document read operations to perform during memory sorting.
Maximum document deletions	20	100	Maximum number of documents that can be deleted per request.
Maximum document updates	20	100	Maximum number of documents that can be updated per request.
Maximum document inserts	20	100	Maximum number of documents that can be inserted per request when using the `insertMany` operation.
Maximum size `_id` values array via `$in`	100	100	Maximum size of an `_id` values array that can be sent via the `$in` operator.
Maximum number of documents returned with each vector search	1000	1000	Maximum number of documents returned with each vector search.
Maximum number of retries following an LWT failure	3	5	Maximum number of retry attempts following a Lightweight Transaction (LWT) failure. For background information about LWTs and linearizable consistency, see this database internals topic.

JSON API prerequisites

cURL, Postman, and Swagger UI options

Install cURL, a utility for running JSON API queries on the command line.
Create a Postman account. Then see our Postman collections:
- JSON API with vector search
- JSON API non-vector
For the JSON API, you can also use the Swagger UI in Astra Portal, which includes "Try It Out" functionality. See the Connect tab for your Astra DB Vector database; scroll down to find the Launch Swagger UI link. The Swagger reference is available at:

https://<db-id>-<region>.apps.astra.datastax.com/api/json/swagger-ui/

Astra DB Vector database, IDs, and auth token in Astra Portal

If you haven’t already, create an Astra DB Vector database using Astra Portal.

Specify the keyspace name, purchase_database, to follow along with values used in this section. For example, on the Create Database dialog in Astra Portal:
After completing the form, click Create Database.
Wait for the database to reach an Active status.
On the Connect tab for your Astra DB Vector database, under Get an application token, use the Database Administrator role and click Generate Token.

Save the values, as you’ll need the following when you submit JSON API operations via curl commands or in Postman:
- ASTRA_DB_ID
- ASTRA_DB_REGION
- ASTRA_DB_APPLICATION_TOKEN
For details, see JSON API reference with vector examples and its Export environment variables section.

Here’s a curl example that brings together the prerequisites:
```
curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "createCollection": {
    "name": "vector_collection",
    "options" : {
      "vector" : {
      "size" : 5,
        "function" : "cosine"
      }
    }
  }
}'
```

JSON API pricing

The JSON API code is available as open source software.

For information about how JSON API read and write compute costs are calculated, see the REST and JSON API and Astra DB pricing pricing topics.

JSON API open-source GitHub repos

JSON API is included for Astra DB Vector databases. You can submit API calls such as createCollection, insert, insertMany, find, findOne, and other operations with or without vector functions. For most Node.js developers today, using the JSON API with Mongoose — while connected to Astra DB Vector databases that provide vector similarity searches — opens up an exciting area of new functionality to explore.

We provide open-source code and sample apps in our public GitHub repos:

Stargate JSON API
Stargate Mongoose
Photography Site sample
Discord Bot sample
E-commerce sample
Typescript Express Reviews sample
create-astradb-mongoose-app, the source files for the movies app that is highlighted on the Astra Portal Connect tab, and described in the JSON API QuickStart with Mongoose

Be sure to clone the repos to take full advantage of the provided resources.

Send us feedback, especially during the public preview, by submitting GitHub Issues in the following open-source repos. Read the contribution guidelines:

JSON API and Mongoose sample applications

See the sample applications that are available in open source GitHub repos

Each sample’s README has details on how to run with an Astra DB Vector database

Also provided is a customizable .env.example file in each sample’s GitHub directory

Photography Site sample, which includes vector search features - for your convenience, this sample is also available in the Awesome Astra gallery
Discord Bot sample
E-commerce sample
Typescript Express Reviews sample

JSON API reference with vector examples

This section describes the operations you can perform with the Astra DB JSON API. Where applicable, Astra Portal or curl examples are shown.

There is a sequence to the operations, in the order presented below.

To follow along with the JSON API examples, we suggest that you create a new Astra DB Vector database in Astra Portal, and specify purchase_database as the keyspace name.

Export environment variables
Create a namespace in Astra Portal
Create a collection
Insert one document
Insert many documents
Find with vector search
Find with vector search projection
FindOne with vector search
FindOneAndUpdate with vector search
FindOneAndReplace with vector search
FindOneAndDelete with vector search

While most of the examples below highlight the use of JSON API vector operations with $vector, you can submit JSON API operations without vector functionality. Most developers today are keen to learn and use AI vector similarity search functionality, thus the emphasis in this topic.

Export environment variables

The curl commands in this section use the following environment variables:

$ASTRA_DB_ID
$ASTRA_DB_REGION
$ASTRA_DB_APPLICATION_TOKEN

If you haven’t already in Astra Portal, on the Connect tab for your Astra DB Vector database, use the Database Administrator role and click Generate Token.

Then in the CLI of you choosing, export the values. Example:

export ASTRA_DB_ID=showing-fake-db-id-value-in-this-example-999999
export ASTRA_DB_REGION=us-east1
export ASTRA_DB_APPLICATION_TOKEN=AstraCS:showing-fake-application-token-value:in-this-example-999999

Be sure to export the latest generated token value to the ASTRA_DB_APPLICATION_TOKEN variable before submitting curl commands.

Create a namespace in Astra Portal

Namespaces are used to logically separate different collections or sets of data within a database. Creating a namespace is one of the first steps in organizing data in a database.

At this time, you must define the namespace in Astra Portal instead of via a JSON API operation. In the context of Astra Portal, we use the term keyspace to represent the database’s namespace.

In this topic’s examples, we’ll use the keyspace / namespace name: purchase_database.

Create a collection

The following JSON payload is designed to create a new collection with specific configurations. This JSON structure is sent via an HTTP POST request to a server in order to initialize a new collection within an already authenticated Astra DB Vector database, particularly for storing vectors with specific properties.

Example:

cURL /api/json/v1/{namespace}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "createCollection": {
    "name": "vector_collection",
    "options" : {
      "vector" : {
      "size" : 5,
        "function" : "cosine"
      }
    }
  }
}'

{
    "status": {
        "ok": 1
    }
}

About 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 will be 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.
  - size: This field indicates the dimension of the vectors to be stored in this collection. The size is set to 5, which means each vector in this collection will have five dimensions.
  - function: Specifies the similarity function to be used when querying or comparing vectors within this collection. The available options are dot_product, euclidean, and cosine. In this payload, it’s set to cosine, which will be used as the default similarity metric for this vector space.

This JSON payload is a concise way to encapsulate all the information needed to create a specialized "vector_collection" with a 5-dimensional vector space using the cosine similarity metric for any relevant operations.

Find collections

The following JSON payload contains a single key-value pair, with the key being "findCollections" and the value being an empty JSON object {}. This operation is useful for getting an overview of the collections that are available for querying, insertion, or other database operations. In this example, because there are no additional parameters or options specified in the empty object, the operation will use default settings to return information about all collections.

Example:

cURL /api/json/v1/purchase_database
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "findCollections": {}
}'

{
  "status": {
    "collections": [
      "vector_collection"
    ]
  }
}

Insert one document

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

This JSON payload is used for inserting a single document into a specified collection within an already authenticated Astra DB Vector database. The payload is sent via an HTTP POST request to an API endpoint, represented by /api/json/v1/{namespace}/{collection}, where {namespace} and {collection} should be replaced in this example with the actual namespace and collection names:

/api/json/v1/purchase_database/vector_collection

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "insertOne": {
        "document": {
            "_id": "4",
            "name": "Coded Cleats Copy",
            "description": "ChatGPT integrated sneakers that talk to you",
            "$vector": [0.25, 0.25, 0.25, 0.25, 0.25]
        }
    }
}'

{
  "status": {
    "insertedIds": [
      "4"
    ]
  }
}

About each key-value pair:

insertOne: This key indicates that only one document is to be inserted into the collection. It holds the details of the document in the form of a nested JSON object.
- document: This nested object contains the key-value pairs that represent the fields and values of the document to be inserted.
  - _id: This is the unique identifier for the document. It is set to the string "4".
  - name: The name of the item represented by this document is "Coded Cleats Copy". This could be useful for search or display purposes.
  - description: This is a more detailed description of the item, which in this case are sneakers integrated with ChatGPT that can "talk to you".
  - $vector: As noted, this is a reserved field name 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 operations that can be applied to vectors. Given that this is a reserved field, the Astra DB Vector database has specialized handling for data stored in this format. That is, optimized query performance for vector similarity.

By sending this JSON payload to the specified API endpoint, a new document with the given _id, name, description, and $vector fields are created within the designated collection in the Astra DB Vector database.

Insert many documents

This JSON payload is designed to insert multiple documents into a specified collection within an already authenticated Astra DB Vector database. The payload is sent via an HTTP POST request to an API endpoint, represented by /api/json/v1/{namespace}/{collection}, where {namespace} and {collection} should be replaced in this example with the actual namespace and collection names:

/api/json/v1/purchase_database/vector_collection

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

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "insertMany": {
     "documents": [
       {
         "_id": "1",
         "name": "Coded Cleats",
         "description": "ChatGPT integrated sneakers that talk to you",
         "$vector": [0.1, 0.15, 0.3, 0.12, 0.05]
        },
        {
          "_id": "2",
          "name": "Logic Layers",
          "description": "An AI quilt to help you sleep forever",
          "$vector": [0.45, 0.09, 0.01, 0.2, 0.11]
        },
        {
          "_id": "3",
          "name": "Vision Vector Frame",
          "description": "Vision Vector Frame - A deep learning display that controls your mood",
          "$vector": [0.1, 0.05, 0.08, 0.3, 0.6]
        }
     ]
   }
}'

{
  "status": {
    "insertedIds": [
      "1",
      "2",
      "3"
    ]
  }
}

About each key-value pair:

insertMany: This key signifies the operation type, indicating that multiple documents will be inserted into the collection. It contains an array of documents specified under the key documents.
- documents: This is an array of JSON objects, where each object represents a single document to be inserted into the collection.
  - First Document:
    
    _id: The unique identifier is set to "1".
    
    name: The name of the item is Coded Cleats, which could be useful for categorization or search.
    
    description: Provides more details about the item, indicating it is a pair of ChatGPT-integrated sneakers that can "talk to you."
    
    $vector: A reserved field name for storing vector data, containing an array [0.1, 0.15, 0.3, 0.12, 0.05].
  - Second Document:
    
    _id: The unique identifier is set to "2".
    
    name: The name of the item is "Logic Layers."
    
    description: Describes the item as "An AI quilt to help you sleep forever."
    
    $vector: Stores vector data in the array [0.45, 0.09, 0.01, 0.2, 0.11].
  - Third Document:
    
    _id: The unique identifier is set to "3".
    
    name: The name of the item is "Vision Vector Frame."
    
    description: Provides details as "A deep learning display that controls your mood."
    
    $vector: Contains vector data [0.1, 0.05, 0.08, 0.3, 0.6].

By sending this JSON payload to the specified API endpoint, you would create three new documents within the designated collection in the database, each with unique identifiers, names, descriptions, and associated vector data. Given that $vector is a reserved field, the Astra DB database offers specialized operations optimized for vector data, such as similarity queries.

Find with vector search

This JSON payload is designed to perform a vector-based search within an already authenticated Astra DB Vector database. The payload is sent via an HTTP POST request to an API endpoint, represented by /api/json/v1/{namespace}/{collection}, where {namespace} and {collection} should be replaced in this example with the actual namespace and collection names:

/api/json/v1/purchase_database/vector_collection

As noted, $vector is a reserved field 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 function.

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

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-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
    }
  }
}'

{
  "data": {
    "documents": [
      {
        "_id": "3",
        "name": "Vision Vector Frame",
        "description": "Vision Vector Frame - A deep learning display that controls your mood",
        "$vector": [
          0.1,
          0.05,
          0.08,
          0.3,
          0.6
        ]
      },
      {
        "_id": "4",
        "name": "Coded Cleats Copy",
        "description": "ChatGPT integrated sneakers that talk to you",
        "$vector": [
          0.25,
          0.25,
          0.25,
          0.25,
          0.25
        ]
      },
      {
        "_id": "2",
        "name": "Logic Layers",
        "description": "An AI quilt to help you sleep forever",
        "$vector": [
          0.45,
          0.09,
          0.01,
          0.2,
          0.11
        ]
      },
      {
        "_id": "1",
        "name": "Coded Cleats",
        "description": "ChatGPT integrated sneakers that talk to you",
        "$vector": [
          0.1,
          0.15,
          0.3,
          0.12,
          0.05
        ]
      }
    ],
    "nextPageState": null
  }
}

About each key-value pair:

find: This key indicates that a "find" operation is to be performed. It holds nested JSON objects that define the search and sort criteria.
- sort: This field specifies the vector against which other vectors in the database will be compared. The $vector is a reserved field name for storing vector data, and here it’s set to [0.15, 0.1, 0.1, 0.35, 0.55]. The Astra DB Vector database uses this vector to perform a similarity search among the documents, sorting them based on how similar their $vector fields are to this specified vector.
- options: This is another nested JSON object that holds additional settings for the "find" operation.
  - limit: This field specifies the maximum number of documents that should be returned by the query. It is set to 100 in this example; meaning that the search will return up to 100 of the most similar documents, sorted according to their similarity to the specified vector.

Find with vector search projection

This JSON payload is designed to perform a vector-based search with projection in an Astra DB Vector database. The payload is sent via an HTTP POST request to an API endpoint, represented by /api/json/v1/{namespace}/{collection}, where {namespace} and {collection} should be replaced in this example with the actual namespace and collection names:

/api/json/v1/purchase_database/vector_collection

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

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

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

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-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, "$similarity" : 1},
    "options" : {
        "limit" : 100
    }
  }
}'

{
  "data": {
    "documents": [
      {
        "_id": "3",
        "$vector": [
          0.1,
          0.05,
          0.08,
          0.3,
          0.6
        ],
        "$similarity": 0.99444735
      },
      {
        "_id": "4",
        "$vector": [
          0.25,
          0.25,
          0.25,
          0.25,
          0.25
        ],
        "$similarity": 0.9087937
      },
      {
        "_id": "2",
        "$vector": [
          0.45,
          0.09,
          0.01,
          0.2,
          0.11
        ],
        "$similarity": 0.7967084
      },
      {
        "_id": "1",
        "$vector": [
          0.1,
          0.15,
          0.3,
          0.12,
          0.05
        ],
        "$similarity": 0.75363994
      }
    ],
    "nextPageState": null
  }
}

About each key-value pair:

find: This key indicates that a "find" or search operation is to be executed. It contains nested JSON objects that define the search criteria, projection, and other options.
- sort: This field specifies the vector against which other vectors in the Astra DB Vector database are to be compared. The $vector key is a reserved field name for storing vector data. The vector is set to [0.15, 0.1, 0.1, 0.35, 0.55]. Documents in the database will be sorted based on their similarity to this vector.
- projection: This field is used to specify which fields should be included in the returned documents.
  - $vector: Setting this value to 1 means that the $vector field will be included in the output.
  - $similarity: Setting this value to 1 means that a field showing the similarity metric between the sorted vector and the vectors in the database will also be included. In the response, the resulting similarity score (such as 0.99444735) is useful for understanding how close each result is to the queried vector.
- options: This nested JSON object contains additional settings for the "find" operation.
  - limit: Specifies the maximum number of documents to be returned. It’s set to 100, meaning the search will return up to the top 100 most similar documents.

FindOne with vector search

This JSON payload is is structured for executing a "findOne" operation with vector-based search criteria in an Astra DB Vector 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/{namespace}/{collection}, where {namespace} and {collection} should be replaced in this example with the actual namespace and collection names:

/api/json/v1/purchase_database/vector_collection

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

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-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}
  }
}'

{
  "data": {
    "document": {
      "_id": "3",
      "$vector": [
        0.1,
        0.05,
        0.08,
        0.3,
        0.6
      ]
    }
  }
}

About each key-value pair:

findOne: This key signifies that the operation aims to find a single document. The value is a nested JSON object that defines how to sort and project the results.
- sort: This field is used to specify the vector against which other vectors in the database will be compared for similarity. The $vector key is a reserved field name for storing vector data. Here, it’s set to the array [0.15, 0.1, 0.1, 0.35, 0.55]. The Astra DB Vector database uses this vector to find the document whose $vector field is most similar to the specified array.
- projection: This nested JSON object specifies which fields should be included in the returned document.
  - $vector: Setting this field to 1 means that the $vector field will be included in the output, allowing you to see the vector data of the returned document.

FindOneAndUpdate with vector search

This JSON payload is designed for a "findOneAndUpdate" operation that incorporates vector-based search in an already authenticated Astra DB Vector database.

The operation aims to find a single document that is most similar to the specified vector, update a field in that document, and then return the updated document.

/api/json/v1/purchase_database/vector_collection

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

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "findOneAndUpdate": {
        "sort" : {"$vector" : [0.15, 0.1, 0.1, 0.35, 0.55]},
        "update" : {"$set" : {"status" : "active"}},
        "options" : {"returnDocument" : "after"}
    }
}'

{
  "data": {
    "document": {
      "_id": "3",
      "name": "Vision Vector Frame",
      "description": "Vision Vector Frame - A deep learning display that controls your mood",
      "$vector": [
        0.1,
        0.05,
        0.08,
        0.3,
        0.6
      ],
      "status": "active"
    }
  },
  "status": {
    "matchedCount": 1,
    "modifiedCount": 1
  }
}

About each key-value pair:

findOneAndUpdate: This key indicates that the operation intends to find one document and update it. The value is a nested JSON object with parameters for sorting, updating, and other options.
- sort: This field specifies the vector to compare against other vectors in the database for similarity. The $vector key is a reserved field name for storing vector data. The array [0.15, 0.1, 0.1, 0.35, 0.55] is used to find the most similar document based on this vector.
- update: This nested JSON object defines how to update the document that is found.
  - $set: The key-value pair "status": "active" indicates that the status field of the found document will be set to "active."
- options: This is another nested JSON object containing additional settings for the operation.
  - returnDocument: The value "after" specifies that the document returned should be the one after the update has been applied. This behavior allows you to see the changes immediately.

FindOneAndReplace with vector search

This JSON payload is designed for a "findOneAndReplace" operation that incorporates vector-based search in an already authenticated Astra DB Vector database.

The operation aims to find the document most similar to a specified vector and replace it with a new document. Then, based on options, the operation can either return the document as it was before replacement, or as it is after the replacement. In this example, we’ll specify after. Also notice that we change the document’s status from active to inactive.

/api/json/v1/purchase_database/vector_collection

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

JSON API: /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "findOneAndReplace": {
        "sort" : {"$vector" : [0.15, 0.1, 0.1, 0.35, 0.55]},
        "replacement" : {
            "_id": "3",
            "name": "Vision Vector Frame",
            "description": "Vision Vector Frame - A deep learning display that controls your mood",
            "$vector": [
                0.1,
                0.05,
                0.08,
                0.3,
                0.6
            ],
            "status": "inactive"
        },
        "options" : {"returnDocument" : "after"}
    }
}'

{
  "data": {
    "document": {
      "_id": "3",
      "name": "Vision Vector Frame",
      "description": "Vision Vector Frame - A deep learning display that controls your mood",
      "$vector": [
        0.1,
        0.05,
        0.08,
        0.3,
        0.6
      ],
      "status": "inactive"
    }
  },
  "status": {
    "matchedCount": 1,
    "modifiedCount": 1
  }
}

About each key-value pair:

findOneAndReplace: This key indicates that the operation is intended to find a single document based on the vector and replace it with a new one. It contains a nested JSON object that outlines the sort criteria, the replacement document, and additional options.
- sort: This field specifies the vector to be used as the comparison measure for finding the most similar document in the database. The $vector is a reserved field name for vector data, and its value here is [0.15, 0.1, 0.1, 0.35, 0.55].
- replacement: This nested JSON object outlines the document that will replace the one found in the database.
  - _id: The unique identifier for the new document is "3".
  - name: The name of the product is "Vision Vector Frame".
  - description: Describes the product as "A deep learning display that controls your mood".
  - $vector: Specifies the vector data as [0.1, 0.05, 0.08, 0.3, 0.6].
  - status: Sets the status of the new document as "inactive".
- options: This is another nested JSON object that holds additional settings for the operation.
  - returnDocument: The value "after" indicates that the returned document should be the one after the replacement is done, allowing you to see the changes immediately.

FindOneAndDelete with vector search

This JSON payload is designed for a "findOneAndDelete" operation that incorporates vector-based search in an already authenticated Astra DB Vector database.

The objective of this operation is to locate a single document in the database that is most similar to a specified vector and then delete it.

/api/json/v1/purchase_database/vector_collection

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

cURL /api/json/v1/{namespace}/{collection}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database/vector_collection \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
    "findOneAndDelete": {
        "sort" : {"$vector" : [0.15, 0.1, 0.1, 0.35, 0.55]}
    }
}'

{
  "data": {
    "document": {
      "_id": "3",
      "name": "Vision Vector Frame",
      "description": "Vision Vector Frame - A deep learning display that controls your mood",
      "$vector": [
        0.1,
        0.05,
        0.08,
        0.3,
        0.6
      ],
      "status": "inactive"
    }
  },
  "status": {
    "deletedCount": 1
  }
}

About each key-value pair:

findOneAndDelete: This key signifies that the operation is intended to find a single document based on a specified vector and then delete it. The value is a nested JSON object containing the sort criteria.
- sort: This field indicates the vector that will be used for the search. The $vector is a reserved field name for vector data, and its value here is [0.15, 0.1, 0.1, 0.35, 0.55]. The Astra DB Vector database uses this vector to locate the most similar document.

Delete a collection

The following JSON payload is designed to delete an existing collection.

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

Example:

cURL /api/json/v1/{namespace}
Result

curl -s --location \
--request POST https://${ASTRA_DB_ID}-${ASTRA_DB_REGION}.apps.astra.datastax.com/api/json/v1/purchase_database \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--data '{
  "deleteCollection": {
    "name": "vector_collection"
  }
}'

{
    "status": {
        "ok": 1
    }
}

About each key-value pair:

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

What’s next?

If you’re new to vector databases and vector search technology, see Astra Vector Search
JSON API QuickStart with Mongoose
JSON API reference
Photography Site sample