Quickstart

Five minutes from here you’ll have a table with a vector<n> column, a few embeddings in it, and a working KNN query — all on the data plane, no pipeline and no engine to provision. A vector<n> column is just another column type.

Want K3 to embed uploaded documents for you? That’s the vector pipeline, and it lives in Pipelines → Quickstart — dodil data vector collection add with an *_embedding_index template. This page is the pure-SQL path: you already have (or will insert) the vectors.

Prerequisites

• dodil CLI installed and dodil auth login done — CLI Basics
• A bucket — kb-prod:

  dodil data bucket create kb-prod -d "Vector demo"

• A Postgres connection string for the pg wire (for the psql tab):

  dodil data connect kb-prod   # emits a pg URL ending in ?sslmode=require

  Use sslmode=require — the pg wire terminates TLS. Avoid prefer: it silently falls back to plaintext, and your password on this wire is your service-account secret.

1. Create a table with a vector column

Pick your embedding dimension up front — the dimension is mandatory and fixed at create time. This demo uses 4-D vectors so you can type them by hand; real embeddings are 768/1024/1536-D.

CREATE TABLE items (
  id        VARCHAR PRIMARY KEY,
  content   VARCHAR,
  embedding vector(4)
);

dodil data table create items -b kb-prod \
  --columns-json '[
    {"name":"id","type":"VARCHAR"},
    {"name":"content","type":"VARCHAR"},
    {"name":"embedding","type":"VECTOR(4)"}
  ]' \
  --merge-key id

2. Insert some vectors

A vector literal is a bracketed list in a string: '[0.1, 0.2, 0.3, 0.4]'.

INSERT INTO items (id, content, embedding) VALUES
  ('a', 'red apple',   '[0.9, 0.1, 0.0, 0.1]'),
  ('b', 'green apple', '[0.8, 0.2, 0.0, 0.1]'),
  ('c', 'blue car',    '[0.0, 0.1, 0.9, 0.2]');

dodil data table upsert items -b kb-prod \
  -r '{"id":"a","content":"red apple","embedding":[0.9,0.1,0.0,0.1]}' \
  -r '{"id":"b","content":"green apple","embedding":[0.8,0.2,0.0,0.1]}' \
  -r '{"id":"c","content":"blue car","embedding":[0.0,0.1,0.9,0.2]}'

3. Query — KNN by vector

Nearest neighbours to [0.85, 0.15, 0.0, 0.1] (near the apples). The three pgvector operators are <=> cosine, <-> L2, <#> inner product.

SELECT id, content, embedding <=> '[0.85, 0.15, 0.0, 0.1]' AS distance
FROM items
ORDER BY distance
LIMIT 3;

dodil data vsearch -b kb-prod -t items --column embedding \
  --vector "0.85,0.15,0.0,0.1" --metric cosine --top-k 3

4. (Optional) Add an ANN index

For large tables, back the column with an approximate index. Small tables are fine on exact scan.

CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);

The opclass must match how you query: vector_cosine_ops for <=>, vector_l2_ops for <->, vector_ip_ops for <#>. Only those three resolve. See Core Concepts → The ANN index.

What you just built

The same table also answers a stock Qdrant or Pinecone client — see External Collection.

Next steps

• Core Concepts — the type vocabulary, metrics, operators, opclasses, and the ANN index
• API Reference → Search — the managed search route (server-side query embedding across pipeline collections)
• Connect & wire adapters — Qdrant / Pinecone / Postgres endpoints + credentials
• Pipelines → Quickstart — the auto-embed-on-ingest path, if you’d rather K3 did the embedding

Cleanup

dodil data table delete items -b kb-prod
dodil data bucket delete kb-prod