Skip to content
QQL
GitHub

Quickstart

This path uses Qdrant REST on port 6333. Start with literal vectors, which need no embedder, then add text embeddings once Ollama is running.

  1. Start Qdrant

    Qdrant
    docker run --rm -p 6333:6333 -p 6334:6334 qdrant/qdrant:v1.19.0

    QQL requires Qdrant 1.19.0 or newer. The tag above pins the version.

  2. Query with literal vectors (no embedder)

    QQLDense collection and filter indexTry in playground
    CREATE COLLECTION quickstart_vectors (
      dense VECTOR(3, COSINE)
    )
    WITH HNSW (m = 16, ef_construct = 100);
    

    CREATE INDEX ON COLLECTION quickstart_vectors FOR category TYPE keyword;
    QQLUpsert and search with literal vectorsTry in playground
    UPSERT INTO quickstart_vectors VALUES
      {id: 1, vector: [0.9, 0.1, 0.2], category: 'qql'},
      {id: 2, vector: [0.1, 0.8, 0.3], category: 'qdrant'};
    

    QUERY [0.9, 0.1, 0.2]
    FROM quickstart_vectors
    WHERE category = 'qql'
    LIMIT 5;

  3. Start the embedder for text queries

    Text steps (USING) need an OpenAI-compatible endpoint. Start Ollama and pull the model before configuring QQL:

    Ollama
    ollama serve ollama pull all-minilm:l6-v2

    Configure QQL connection and embedder settings (via qql setup or environment variables):

    Setup
    qql setup --url http://localhost:6333 --yes export EMBED_URL=http://localhost:11434/v1/embeddings export EMBED_MODEL=all-minilm:l6-v2 export EMBED_DIM=384

    Confirm the endpoint dim matches the config before loading data:

    Doctor
    qql doctor

  4. Upsert text content

    QQLEmbed text into the dense vectorTry in playground
    CREATE COLLECTION docs (
      dense VECTOR(384, COSINE)
    )
    WITH HNSW (m = 16, ef_construct = 100);
    

    CREATE INDEX ON COLLECTION docs FOR category TYPE keyword;
    

    UPSERT INTO docs VALUES
      {id: 1, text: 'QQL provides typed vector retrieval', category: 'qql'},
      {id: 2, text: 'Qdrant stores dense and sparse vectors', category: 'qdrant'} USING DENSE MODEL 'all-minilm:l6-v2';

  5. Search

    QQLFiltered searchTry in playground
    QUERY 'typed query language'
    FROM docs
    USING dense
    WHERE category = 'qql'
    LIMIT 5;

Save the statements as quickstart.qql. Verify it offline with qql lint, then execute it with qql run:

Lint and execute the script
qql lint quickstart.qql qql run quickstart.qql

Use qql explain "QUERY ..." to inspect a plan offline without sending it to Qdrant. Use qql doctor "QUERY ..." (or qql check) to triage format, explain, embedder dim, vector topology, and backend health in one pass.

Already have a Qdrant application?

Section titled “Already have a Qdrant application?”

You do not have to rewrite existing SDK calls by hand. qql record proxies a live application and captures what it sends, and qql convert turns that captured REST JSON into the QQL statements above.

Capture live traffic, then convert
cargo install qql-cli --locked --features record


# ... or from a local checkout: cargo build --release -p qql-cli --features record


# Qdrant keeps its address; point the app at the recorder.


qql record --listen 127.0.0.1:6334 --target http://127.0.0.1:6333 \
--out capture.jsonl --qql-out capture.qql


# Review the captured requests as QQL.


qql convert --collection docs capture.jsonl

See Operations > Convert REST JSON for the wrapped/bare input formats, coverage, and limits.