Skip to content

VectorsDB

Documents_

Create, read, update, and delete documents in Appwrite VectorsDB. Learn how to store embedding vectors and metadata in your collections.

3 min read

Raw

Each piece of data in Appwrite VectorsDB is a document. A document's data follows the fixed schema provisioned by its collection: an embeddings vector and an optional metadata object.

An embedding is a list of numbers that represents the meaning of a piece of content, so similar content gets similar numbers. You can bring your own vectors or generate embeddings from text with Appwrite's built-in models.

The embeddings array is required, and its length must equal the dimension you set when creating the collection. The metadata field is free-form JSON, so you can attach any data you want to keep alongside each vector.

Create documents

Use the createDocument method to add a document to a collection. Appwrite Server SDKs require an API key.

const sdk = require('node-appwrite');


const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key


const vectorsDB = new sdk.VectorsDB(client);


const result = await vectorsDB.createDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: sdk.ID.unique(),
    data: {
        embeddings: [0.12, 0.84, 0.33, 0.57],
        metadata: { title: 'Hamlet', year: 1601 }
    },
    permissions: [sdk.Permission.read(sdk.Role.any())] // optional
});

To insert many documents in a single request, use bulk operations instead of calling createDocument in a loop.

Get document

Use the getDocument method to read a single document by its ID.

const sdk = require('node-appwrite');


const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key


const vectorsDB = new sdk.VectorsDB(client);


const result = await vectorsDB.getDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>'
});

List documents

Use the listDocuments method to read documents from a collection. Pass queries to filter, order, and paginate the results.

To rank documents by similarity to a query vector, use a vector search query instead. See Vector search.

listDocuments sends queries in the URL. When your queries are too long for that, createQuery takes the same arguments in the request body and returns the same document list. See Send queries in the request body.

const sdk = require('node-appwrite');


const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key


const vectorsDB = new sdk.VectorsDB(client);


const result = await vectorsDB.listDocuments({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    queries: [
        sdk.Query.limit(10)
    ]
});

Update document

Use the updateDocument method to update a document. The update is a patch, so you only pass the fields you want to change. To change the vector, pass a new embeddings array of the same length as the collection's dimension.

const sdk = require('node-appwrite');


const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key


const vectorsDB = new sdk.VectorsDB(client);


const result = await vectorsDB.updateDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: {
        embeddings: [0.20, 0.10, 0.60, 0.10],
        metadata: { title: 'Hamlet', year: 1602 }
    }
});

Upsert document

Use the upsertDocument method to create a document if it doesn't exist, or update it if it does.

const sdk = require('node-appwrite');


const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key


const vectorsDB = new sdk.VectorsDB(client);


const result = await vectorsDB.upsertDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: {
        embeddings: [0.50, 0.50, 0.50, 0.50],
        metadata: { title: 'Hamlet', year: 1603 }
    }
});

Delete document

Use the deleteDocument method to remove a document from a collection.

const sdk = require('node-appwrite');


const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1') // Your API Endpoint
    .setProject('<YOUR_PROJECT_ID>') // Your project ID
    .setKey('<YOUR_API_KEY>'); // Your secret API key


const vectorsDB = new sdk.VectorsDB(client);


const result = await vectorsDB.deleteDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>'
});

Permissions

To access documents through a Client SDK, you must grant the relevant permissions. By default, Appwrite doesn't grant any user permissions when a new collection is created.

You can configure permissions at the collection level, or enable documentSecurity on the collection to also set permissions on individual documents.

Learn about configuring permissions.

Next steps

Continue learning with these related guides:

Vector search

Rank documents by similarity to a query vector using cosine, dot product, or Euclidean distance.

Bulk operations

Create, update, upsert, and delete many documents in a single request.

Collections

Configure the dimension and indexes that define how your vectors are stored and searched.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.