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 also 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/
The JSON API collection in our Postman workspace.

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 JSON API supports up to five collections in a namespace. The JSON API uses Storage Attached Indexing (SAI), and each Astra DB Vector database limits the number of indexes in a keyspace to five.

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.

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 REST and JSON API and Astra DB pricing.

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:

Prerequisites

cURL, Postman, and Swagger UI options

Install cURL, a utility for running JSON API queries on the command line.
If you prefer, you can use Postman as a client interface for exploring the APIs.

For the JSON APIs, you can use the Swagger UI, which includes Try It functionality.

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.
Generate a global Astra DB application token via the Settings > Tokens dialog. It’s available from the left-side navigation bar in Astra Portal. Use that global token option instead of Generate Token on the Connect tab. Specify the Database Administrator role when you run the token generation in Settings > Tokens.

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.

A curl example:
```
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"
      }
    }
  }
}'
```

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, export the values for your Astra DB Vector database. You can get these values in Astra Portal.

Export examples:

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

If your Astra DB Vector database needs multiple keyspaces, we recommend that you generate an ASTRA_DB_APPLICATION_TOKEN value via the global Settings > Tokens dialog. It’s available from the left-side navigation bar in Astra Portal. Use that global option instead of Generate Token on the Connect tab. Specify the Database Administrator role when you run the token generation in Settings > Tokens.

Example:

Using Settings then Tokens dialog with Database Administrator in Astra Portal.

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.

Additionally, 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.