Skip to content

Quickstart

This guide outlines the essential steps for using KDB.AI. Before proceeding, ensure your environment is set up as described in Prerequisites and has the necessary information to connect to KDB.AI Server.

If you prefer to start in GitHub or Google Colab, refer to the Quickstart sample project.

1. Connect to the service

The Python client connects through qIPC on port 8082. The REST API runs on port 8081.

import pandas as pd
import kdbai_client as kdbai

# Connect via qIPC on port 8082
session = kdbai.Session(host='localhost', port=8082, mode='qipc')
database = session.database('default')

import kdbai_client as kdbai

# Connect via REST on port 8081
session = kdbai.Session(endpoint='http://localhost:8081', mode='rest')
database = session.database('default')

KDBAI_ENDPOINT='http://localhost:8081'
KDBAI_TOKEN=''

echo "=== Readiness check ==="
curl -s -H "X-Api-Key: $KDBAI_TOKEN" $KDBAI_ENDPOINT/api/v2/ready
echo ""

2. Create a table

Define a schema and a flat (exact) vector index for 3-dimensional embeddings using L2 distance, then create the table:

schema = [
    {"name": "label",  "type": "str"},
    {"name": "vector", "type": "float32s"}
]

indexes = [
    {
        "name": "vec_idx",
        "type": "flat",
        "column": "vector",
        "params": {"dims": 3, "metric": "L2"}
    }
]

table = database.create_table("quickstart", schema=schema, indexes=indexes)

echo "=== Create table ==="
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KDBAI_TOKEN" \
  -d '{
    "table": "quickstart",
    "schema": [
      {"name": "label",  "type": "symbol"},
      {"name": "vector", "type": "reals"}
    ],
    "indexes": [
      {
        "name": "vec_idx",
        "type": "flat",
        "column": "vector",
        "params": {"dims": 3, "metric": "L2"}
      }
    ]
  }' \
  $KDBAI_ENDPOINT/api/v2/databases/default/tables | jq

Full schema definition specifications are available on the Manage tables page.

3. List tables

Verify the table was created:

print(database.tables)
# Expected: [KDBAI table "quickstart"]

echo "=== List tables ==="
curl -s \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KDBAI_TOKEN" \
  $KDBAI_ENDPOINT/api/v2/databases/default/tables | jq

4. Insert data

Each vector represents a point in a three-dimensional space. The red fruits (apple, apricot, cherry, raspberry, strawberry) cluster together, while banana and lemon occupy different regions, making search results easy to predict and interpret.

data = pd.DataFrame({
    "label":  ["apple", "apricot", "cherry", "raspberry", "strawberry", "banana", "lemon"],
    "vector": [
        [0.9, 0.1, 0.0],   # apple
        [0.8, 0.2, 0.0],   # apricot   – close to apple
        [0.7, 0.0, 0.2],   # cherry
        [0.8, 0.0, 0.1],   # raspberry
        [0.9, 0.0, 0.1],   # strawberry
        [0.5, 0.8, 0.1],   # banana    – different region
        [0.0, 0.0, 1.0],   # lemon     – the odd one out
    ],
})
table.insert(data)
print("Inserted rows:", len(table.query()))
# Expected: 7

echo "=== Insert data ==="
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KDBAI_TOKEN" \
  -d '{
    "payload": [
      {"label": "apple",      "vector": [0.9, 0.1, 0.0]},
      {"label": "apricot",    "vector": [0.8, 0.2, 0.0]},
      {"label": "cherry",     "vector": [0.7, 0.0, 0.2]},
      {"label": "raspberry",  "vector": [0.8, 0.0, 0.1]},
      {"label": "strawberry", "vector": [0.9, 0.0, 0.1]},
      {"label": "banana",     "vector": [0.5, 0.8, 0.1]},
      {"label": "lemon",      "vector": [0.0, 0.0, 1.0]}
    ]
  }' \
  $KDBAI_ENDPOINT/api/v2/databases/default/tables/quickstart/insert | jq

5. Query the table

The query function accepts a wide range of arguments to filter, aggregate, and sort. Run ?table.query to see them all.

data = table.query()
print(f'Table data:\n {data}')

echo "=== Table data ==="
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KDBAI_TOKEN" \
  -d '{}' \
  $KDBAI_ENDPOINT/api/v2/databases/default/tables/quickstart/query | jq

The dimension of input query vectors must match the vector embedding dimensions defined in the schema.

The query vector [0.88, 0.12, 0.0] sits very close to apple in the vector space. The search returns the three nearest neighbors using L2 (Euclidean Distance) similarity – all red fruits. lemon never appears.

The key in the vectors dictionary must match the index name defined in your schema. In this example, vec_idx matches the index name set in step 2.

query = [[0.88, 0.12, 0.0]]

results = table.search(vectors={"vec_idx": query}, n=3)
print("Query vector:", query[0])
print("Top-3 nearest neighbors:\n", results[0][["label", "__nn_distance"]])
# Expected order: apple → apricot → strawberry (lemon never appears)

echo "=== Similarity search results ==="
echo "Query vector: [0.88, 0.12, 0.0]"
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $KDBAI_TOKEN" \
  -d '{
    "vectors": {"vec_idx": [[0.88, 0.12, 0.0]]},
    "n": 3,
    "options": {"distanceColumn": "__nn_distance"}
  }' \
  $KDBAI_ENDPOINT/api/v2/databases/default/tables/quickstart/search | jq
# Expected order: apple → apricot → strawberry (lemon never appears)

The search API supports batch querying and filtered search.

7. Delete a table

Once you delete a table, you cannot use it again. The associated index is also removed.

database.table("quickstart").drop()

echo "=== Drop table ==="
curl -s -X DELETE \
  -H "X-Api-Key: $KDBAI_TOKEN" \
  $KDBAI_ENDPOINT/api/v2/databases/default/tables/quickstart | jq

Next steps

Now that you have completed the quickstart, you can start working with your own data:

For advanced deployment options such as Docker Compose, air-gapped environments, and custom data directories, refer to the Configuration Guide.

Samples

Explore the following resources: