Workflow: Vector Search Lifecycle

This workflow covers vector setup through retrieval, including API fallback for external vector writes.

When To Use

Building or validating retrieval over document embeddings.
Testing quality with top-k/min-score tuning.
Managing manual/external vector ingestion.

Step 1: Configure vector engine


dodil k3 \
  vector-store create --bucket "$K3_BUCKET" --mode auto

Step 2: Create collection

CLI collection create:


dodil k3 \
  vector-collection add contracts-v1 \
  --bucket "$K3_BUCKET" \
  --dimensions 1536 \
  --metric cosine

For template-driven vector collection with contract inputs, use API:


curl -sS -X POST "https://k3.dev.dodil.io/$K3_BUCKET/vector/pipelines" "${AUTH[@]}" "${JSON[@]}" \
  -d '{
    "bucket": "'$K3_BUCKET'",
    "name": "contracts-pipeline-col",
    "template_id": "object_embedding_index"
  }'

Step 3: Ensure data has been ingested

Run the source/ingest workflow from 01-source-to-ingest.md so searchable vectors exist.

Step 4: Search from CLI


dodil k3 \
  search "termination terms in lease agreements" \
  --bucket "$K3_BUCKET" \
  --collection contracts-v1 \
  --top-k 8 \
  --min-score 0.2

Step 5: Search from canonical API route


curl -sS -X POST "https://k3.dev.dodil.io/$K3_BUCKET/vector/search" "${AUTH[@]}" "${JSON[@]}" \
  -d '{
    "bucket": "'$K3_BUCKET'",
    "text": "termination terms in lease agreements",
    "top_k": 8,
    "min_score": 0.2,
    "include_content": true
  }'

Compatibility route (legacy clients):


curl -sS -X POST "https://k3.dev.dodil.io/$K3_BUCKET/search/vector" "${AUTH[@]}" "${JSON[@]}" \
  -d '{"text":"termination terms in lease agreements"}'

Step 6: External vector upsert (API fallback)

Use this when CLI commands are not available for vector writes:


curl -sS -X PUT "https://k3.dev.dodil.io/$K3_BUCKET/vector/collections/<collection_id>/vectors" "${AUTH[@]}" "${JSON[@]}" \
  -d '{
    "bucket": "'$K3_BUCKET'",
    "collection_id": "<collection_id>",
    "vectors": [
      {
        "id": "doc-1#1",
        "dense_float": {"values": [0.11, 0.52, 0.07]},
        "metadata": {"doc_type": "contract", "year": 2026}
      }
    ]
  }'

Tuning Tips

Increase top-k for recall, then apply rerank/filter in application.
Raise min-score to reduce weak matches.
Use collection_name or CLI --collection to avoid cross-collection noise.

Next: Table Lifecycle and SQL Flow