Skip to main content
Learn

Write Records with Vectors

RushDB lets you attach pre-computed embedding vectors to records at write time, eliminating the need for a separate bulk-upsert call. Any operation that creates or modifies records accepts a vectors parameter.

This feature requires at least one external index on the target (label, propertyName). It works on RushDB Cloud and on a self-hosted engine, except inside a transaction on a self-hosted engine: the engine cannot stage inline vectors, so the SDK throws DirectModeError before sending the write. Write the vectors after the commit with upsertVectors, or outside the transaction.

vectors parameter format​

FieldTypeRequiredDescription
propertyNamestringyesProperty name this vector is associated with
vectornumber[]yesPre-computed embedding vector
similarityFunctionstringnoRequired when multiple indexes exist on the same property
indexstringnoThe index to write to, by name (or id). Overrides selection by property and shape.

Create a Record with Vectors​

Record creation and vector storage happen atomically in one request.

db.records.create()

record = db.records.create(
    label="Article",
    data={
        "title": "How transformers work",
        "body": "Attention is all you need ...",
    },
    vectors=[
        {"propertyName": "body", "vector": my_embedder.embed("Attention is all you need ...")}
    ],
)
print(record.id)  # record created AND vector written atomically

Upsert with Vectors​

upsert is idempotent on the record's natural key. Passing vectors writes or replaces the stored vector in the same call.

db.records.upsert()

# First call — creates the record + writes vector
r1 = db.records.upsert(
    label="Article",
    data={"slug": "transformers-101", "title": "Transformers 101", "body": "..."},
    options={"mergeBy": ["slug"], "mergeStrategy": "append"},
    vectors=[{"propertyName": "body", "vector": v1}],
)

# Second call — same slug → updates data + replaces the vector
r2 = db.records.upsert(
    label="Article",
    data={"slug": "transformers-101", "title": "Transformers 101 (revised)", "body": "Updated ..."},
    options={"mergeBy": ["slug"], "mergeStrategy": "append"},
    vectors=[{"propertyName": "body", "vector": v2}],
)
# r1.id == r2.id

Set with Vectors​

set replaces all properties of a record. Including vectors writes those vectors at the same time.

db.records.set()

db.records.set(
    target=record,
    label="Product",
    data={"name": "Widget Pro", "price": 19.99},
    vectors=[{"propertyName": "description", "vector": new_vec}],
)

Create Multiple Records with Vectors​

createMany / create_many accepts a top-level vectors array indexed by row position — each entry is a list of vector entries for that row.

For the common case of one vector per record, you can pass a flat VectorEntry[] instead of the nested VectorEntry[][] — the SDK auto-wraps it into per-row entries.

db.records.create_many()

db.records.create_many(
    label="Product",
    data=[
        {"name": "Alpha", "description": "First product"},
        {"name": "Beta",  "description": "Second product"},
        {"name": "Gamma", "description": "Third product"},
    ],
    vectors=[
        [{"propertyName": "description", "vector": [1, 0, 0]}],  # row 0
        [{"propertyName": "description", "vector": [0, 1, 0]}],  # row 1
        [{"propertyName": "description", "vector": [0, 0, 1]}],  # row 2
    ],
)

Sparse vectors — any rows beyond vectors length are skipped:

db.records.create_many(
    label="Product",
    data=[{"name": "Alpha"}, {"name": "Beta"}, {"name": "Gamma"}],
    vectors=[[{"propertyName": "description", "vector": my_vec}]],  # only row 0
)

Flat form — one vector per record, auto-wraps to per-row entries:

db.records.create_many(
    label="Product",
    data=[{"name": "Alpha"}, {"name": "Beta"}],
    vectors=[{"propertyName": "description", "vector": [1, 0, 0]}],  # flat list
)

Import CSV with Vectors​

CSV is a raw string, so per-row vectors are supplied separately. Row indices are 0-based after the header is consumed.

db.records.import_csv()

csv_data = """name,description
Alpha,First product
Beta,Second product
Gamma,Third product"""

db.records.import_csv(
    label="Product",
    data=csv_data,
    vectors=[
        [{"propertyName": "description", "vector": [1, 0, 0]}],  # csv row 0
        [{"propertyName": "description", "vector": [0, 1, 0]}],  # csv row 1
        [{"propertyName": "description", "vector": [0, 0, 1]}],  # csv row 2
    ],
)

Multiple vectors in one call​

Write vectors for multiple properties or indexes in a single operation:

db.records.create(
    label="Document",
    data={"title": "Multi-modal doc", "abstract": "...", "fullText": "..."},
    vectors=[
        {"propertyName": "abstract",  "vector": abstract_vec},
        {"propertyName": "fullText",  "vector": full_text_vec},
    ],
)

Disambiguation​

When a (label, propertyName) has multiple external indexes (e.g. cosine and euclidean), name the target with index, or specify similarityFunction, in each vector entry to route to the correct index. Omitting it when multiple indexes match returns 422 Unprocessable Entity.

db.records.create(
    label="Product",
    data={"name": "Widget"},
    vectors=[
        {"propertyName": "embedding", "vector": vec, "similarityFunction": "cosine"}
    ],
)

See also​