Quick Start

Creating a database

To create a database, visit the dashboard and navigate to the databases page.

Click the green plus button on the bottom right to bring up the create database modal

Fill in the form, setting the dimension to 4, type to "sandbox" and region to "us-east-2"

After creating the database, take note of the database ID.

note

Sandbox databases are free but have limitations. View the limits page for more information.

Authentication

To authenticate with the database, you will need to generate an API key. To do this, navigate to the databases page and click the key symbol next to the database you want to access. Take note of the API key and the database ID.

Connecting

Once you've created a database and generated an API key, you can connect to the database using the client library.

Install the client library:

JavaScript

npm install @svectordb/client

Python

pip install svectordb

Next let's create the basic skeleton:

JavaScript

const { DatabaseService } = require('@svector/client');

const region = 'us-east-2';
const apiKey = 'f4ead19a-bac7-4ff0-b379-d3f634ed180f'; // replace with your API key
const databaseId = 'f39434565486ee15'; // replace with your database ID

const client = new DatabaseService({
    endpoint: `https://${region}.api.svectordb.com`,
    apiKey: apiKey
});

(async () => {
    // Code goes here
})()

Python

import asyncio
import random

from svectordb.client import DatabaseService
from svectordb.config import Config
from svectordb.models import *
from smithy_http.aio.identity.apikey import ApiKeyIdentity, ApiKeyIdentityResolver

region = 'us-east-2'
apiKey = '2e607c5f-aaac-4d19-9824-4315b135484f' # replace with your API key
databaseId = 'e65c1cd5e2afbcec' # replace with your database ID

async def main() -> None:
    client = DatabaseService(Config(
        endpoint_uri=f"https://{region}.api.svectordb.com",
        api_key_identity_resolver=ApiKeyIdentityResolver(api_key=ApiKeyIdentity(api_key=apiKey)))
    )
        
    # Code goes here


if __name__ == "__main__":
    asyncio.run(main())

Writing data

To add data use the setItem method, this will upsert the data into the database. Let's insert 10 random documents:

JavaScript

for (let i = 0; i < 10; i++) {
    await client.setItem({
        databaseId,
        key: `random-${i}`,
        value: Buffer.from(`Hello world #${i}!`), // Value is stored as bytes, use Buffer.from to convert a string to bytes
        vector: [Math.random(), Math.random(), Math.random(), Math.random()]
    });
}

Python

for i in range(10):
    await client.set_item(SetItemInput(
        database_id=databaseId,
        key=f"random-{i}",
        value=f"Hello world #{i}!".encode(),
        vector=[random.random(), random.random(), random.random(), random.random()]
    ))

Now let's see the data we just inserted:

JavaScript

  const documents = await client.listItems({databaseId});
  console.log(`Found ${documents.items.length} documents`)
  console.log(documents);

Python

  documents = await client.list_items(ListItemsInput(database_id=databaseId))
  print(f"Found {len(documents.items)} documents")
  print(documents)

You can also get a single document by key:

JavaScript

  const document = await client.getItem({databaseId, key: 'random-1'});
  console.log(document);

Python

  document = await client.get_item(GetItemInput(database_id=databaseId, key="random-1"))
  print(document)

To delete a document, use the deleteItem method:

JavaScript

await client.deleteItem({databaseId, key: 'random-1'});

Python

await client.delete_item(DeleteItemInput(database_id=databaseId, key="random-1"))

Querying data

To query data, use the queryItems method. Let's query the 5 closest documents to the vector [0.5, 0.5, 0.5, 0.5]:

JavaScript

  const results = await client.query({
      databaseId,
      query: {
          vector: [0.5, 0.5, 0.5, 0.5]
      },
      maxResults: 5,
  });

  console.log(results);

Python

  results = await client.query(QueryInput(
      database_id=databaseId,
      query=QueryTypeVector([0.5, 0.5, 0.5, 0.5]),
      max_results=5
  ))

  print(results)

You can also query for vectors closest to an existing document:

JavaScript

const results = await client.query({
    databaseId,
    query: {
        key: 'random-0'
    },
    maxResults: 5,
});

console.log(results);

Python

  results = await client.query(QueryInput(
      database_id=databaseId,
      query=QueryTypeKey("random-0"),
      max_results=5
  ))

  print(results)

Full example

tip

You must replace apiKey and databaseId with your own values, see the Creating a database and Authentication sections for more information.

JavaScript

const { DatabaseService } = require('@svector/client');

const region = 'us-east-2';
const apiKey = 'f4ead19a-bac7-4ff0-b379-d3f634ed180f'; // replace with your API key
const databaseId = 'f39434565486ee15'; // replace with your database ID

const client = new DatabaseService({
    endpoint: `https://${region}.api.svectordb.com`,
    apiKey: apiKey
});

(async () => {
    // Insert 10 random documents
    for (let i = 0; i < 10; i++) {
        await client.setItem({
            databaseId,
            key: `random-${i}`,
            value: Buffer.from(`Hello world #${i}!`), // Value is stored as bytes, use Buffer.from to convert a string to bytes
            vector: [Math.random(), Math.random(), Math.random(), Math.random()]
        });
    }

    // List documents
    const documents = await client.listItems({databaseId});
    console.log(`Found ${documents.items.length} documents`)
    console.log(documents);

    // Get a single document
    const document = await client.getItem({databaseId, key: 'random-1'});
    console.log('Document with key "random-1"');
    console.log(document);

    // Delete a document
    await client.deleteItem({databaseId, key: 'random-1'});

    // Query documents
    const queryByVector = await client.query({
        databaseId,
        query: {
            vector: [0.5, 0.5, 0.5, 0.5]
        },
        maxResults: 5,
    });

    console.log('Query by vector');
    console.log(queryByVector);

    const queryByKey = await client.query({
        databaseId,
        query: {
            key: 'random-0'
        },
        maxResults: 5,
    });

    console.log('Query by key');
    console.log(queryByKey);
})();

Python

  import asyncio
  import random

  from svectordb.client import DatabaseService
  from svectordb.config import Config
  from svectordb.models import *
  from smithy_http.aio.identity.apikey import ApiKeyIdentity, ApiKeyIdentityResolver

  region = 'us-east-2'
  apiKey = '2e607c5f-aaac-4d19-9824-4315b135484f'; # replace with your API key
  databaseId = 'e65c1cd5e2afbcec'; # replace with your database ID

  async def main() -> None:
      client = DatabaseService(Config(
          endpoint_uri=f"https://{region}.api.svectordb.com",
          api_key_identity_resolver=ApiKeyIdentityResolver(api_key=ApiKeyIdentity(api_key=apiKey)))
      )
          
      # Insert 10 random documents

      for i in range(10):
          await client.set_item(SetItemInput(
              database_id=databaseId,
              key=f"random-{i}",
              value=f"Hello world #{i}!".encode(),
              vector=[random.random(), random.random(), random.random(), random.random()]
          ))

      # List documents
          
      documents = await client.list_items(ListItemsInput(database_id=databaseId))
      print(f"Found {len(documents.items)} documents")
      print(documents)

      # Get a single document

      document = await client.get_item(GetItemInput(database_id=databaseId, key="random-1"))
      print("Document with key ""random-1""")
      print(document)

      # Delete a document

      await client.delete_item(DeleteItemInput(database_id=databaseId, key="random-1"))

      # Query documents

      queryByVector = await client.query(QueryInput(
          database_id=databaseId,
          query=QueryTypeVector([0.5, 0.5, 0.5, 0.5]),
          max_results=5
      ))

      print("Query by vector")
      print(queryByVector)

      queryByKey = await client.query(QueryInput(
          database_id=databaseId,
          query=QueryTypeKey("random-0"),
          max_results=5
      ))

      print("Query by key")
      print(queryByKey)


  if __name__ == "__main__":
      asyncio.run(main())