Embeddings

OmniGraph can turn query text into a vector for nearest($document.embedding, $text). Use the same provider and model that produced the stored document vectors; vectors from different models are not comparable.

Generated vectors are finite, nonzero, and L2-normalized before use. The target Vector(N) property determines their required dimension.

Providers

For direct or embedded use, configure the provider with environment variables:

The default OpenRouter model is openai/text-embedding-3-large. The direct OpenAI default is text-embedding-3-large; Gemini defaults to gemini-embedding-2.

Cluster configuration

Cluster-served graphs select a named provider in cluster.yaml:

providers:
  embedding:
    default:
      kind: openai-compatible
      base_url: https://openrouter.ai/api/v1
      model: openai/text-embedding-3-large
      api_key: ${OPENROUTER_API_KEY}

graphs:
  knowledge:
    schema: knowledge.pg
    embedding_provider: default

Inline API keys are rejected. ${ENV_VAR} references are resolved when the server starts, not when the cluster configuration is planned or applied.

Schema annotation

Associate a vector with its source text:

node Document {
  slug: String @key
  body: String
  embedding: Vector(1536) @embed("body", model="openai/text-embedding-3-large") @index
}

When model is recorded, a text nearest query is rejected unless the active provider resolves to exactly that model id. Changing the recorded source or model is not an in-place schema migration; rebuild or re-embed the data instead.

@embed does not populate the property during a load, even with an embedding provider configured. Supplied vectors are preserved, omitted nullable vectors remain null, and missing required vectors refuse the load. Supply vectors in input data or prepare seed files with the offline command.

Successful HTTP and CLI JSON load results include embedding_generation: "unsupported" means the load touched a node type with an @embed property; null means it did not. This describes the load capability, including when every vector was supplied. Human CLI output prints the corresponding guidance.

Offline file pipeline

omnigraph embed reads and writes JSONL files; it does not mutate a graph.

omnigraph embed --input raw.jsonl --output embedded.jsonl --spec embeddings.json

By default it fills missing vectors. Use --reembed-all to replace selected vectors or --clean to remove them. --type and --select restrict the records processed. A seed manifest can be supplied with --seed instead of separate input, output, and spec paths.