Skip to main content

Quick Start

This walks through the core DBAPI directly against Milvus Lite — no server to stand up. The same statements work unchanged against a real Milvus deployment; only the uri passed to connect() changes (see Core → Overview).

Connect​

import milvusql

conn = milvusql.connect(uri="./quickstart.db")  # a local file = Milvus Lite
cur = conn.cursor()

Create a collection​

cur.execute("""
    CREATE TABLE items (
        id BIGINT PRIMARY KEY AUTO_INCREMENT,
        embedding VECTOR(8),
        category VARCHAR(64)
    ) WITH (shards=1, consistency_level='Bounded')
""")

cur.execute("""
    CREATE INDEX idx_emb ON items (embedding) USING HNSW
    WITH (metric_type='COSINE', M=16, ef_construction=200)
""")

cur.execute("LOAD TABLE items")

id is BIGINT (Milvus's primary key must be INT64 or VARCHAR) and is created before the index — Milvus needs an index on a vector field before the collection can be loaded and searched.

Insert​

Vectors are bind parameters, never inlined into the SQL text:

cur.execute(
    "INSERT INTO items (embedding, category) VALUES (:emb, :cat)",
    {"emb": [0.1] * 8, "cat": "book"},
)
cur.execute(
    "INSERT INTO items (embedding, category) VALUES (:emb, :cat)",
    {"emb": [0.9] * 8, "cat": "movie"},
)
cur.execute(
    """
    SELECT id, category FROM items
    WHERE category = :cat
    ORDER BY embedding <=> :q
    LIMIT 5
    SEARCH PARAMS (ef_search=64)
    """,
    {"cat": "book", "q": [0.1] * 8},
)
print(cur.fetchall())
# [(1, 'book')]

<=> is cosine distance (matching the index's metric_type='COSINE' above), spelled exactly as pgvector spells it — see MilvusQL Concepts for the full operator table.

Delete​

cur.execute("DELETE FROM items WHERE category = :cat", {"cat": "movie"})
print(cur.rowcount)  # 1

The same thing, async​

import asyncio
from milvusql import aio

async def main():
    conn = aio.connect(uri="./quickstart.db")
    cur = conn.cursor()
    await cur.execute("SELECT id, category FROM items LIMIT 5")
    print(await cur.fetchall())
    await conn.close()

asyncio.run(main())

milvusql.aio isn't PEP 249 (a coroutine can't be, by definition) — it's a separate, asyncio-native surface built over pymilvus.AsyncMilvusClient and the exact same dispatch table as the sync Cursor. See Core → Sync and Async.

Next steps​

  • MilvusQL Concepts — the language itself: operators, bind params, clause order
  • SQLAlchemy — if you'd rather work through Core/ORM
  • Django — if you're wiring this into a Django project