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).

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

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.

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
)

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), 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​