Skip to content
Omnio-js
Esc
↑↓navigate↵open⌘Jpreview
On this page

Object model

Reference for OmnioObject fields, mutable metadata, and record types.

OmnioObject

OmnioObject is the logical unit that combines an entity with its metadata.

type OmnioObject<TUserMetadata = Record<string, unknown>> = {
  key: OmnioKey;
  entityId: string;
  contentType: string;
  createdAt: string;
  updatedAt: string;
  size: number;
  hash?: string;
  hashAlgorithm?: string;
  tags: readonly string[];
  description?: string;
  userMetadata: TUserMetadata;
  embedding?: Float32Array;
  embeddingDims?: number;
  embeddingModel?: string;
  embeddingSource?: EmbedSource;
};
Field Description
key OmnioKey that identifies the object.
entityId Entity storage key, represented as a UUID.
contentType Lowercased content type.
createdAt Creation time as an ISO 8601 string.
updatedAt Update time as an ISO 8601 string.
size Byte size.
hash Hash of the bytes, when available.
hashAlgorithm Hash algorithm such as "sha256".
tags Tags for filtering. They are not embedded.
description Optional text that can be embedded.
userMetadata Arbitrary application metadata.
embedding Embedding vector, when generated.
embeddingDims Embedding dimensions.
embeddingModel Model name used for the embedding.
embeddingSource Origin of the embedding.

Entity-derived values

size, hash, hashAlgorithm, and createdAt derive from the bytes. updateObjectMetadata cannot change them.

entityId points to the stored entity. putObject and copyObject create a new entityId, while renameObject keeps it. Bytes for a given entityId never change.

Mutable metadata

type ObjectMetadataPatch<TUserMetadata = Record<string, unknown>> = {
  contentType?: string;
  description?: string;
  tags?: readonly string[];
  userMetadata?: TUserMetadata;
  updatedAt: string;
};

Omitted fields are unchanged. An empty tags array removes all tags.

Embedding source

type EmbedSource =
  | { kind: "custom"; model: string }
  | { kind: "description"; model: string }
  | { kind: "image"; model: string }
  | { kind: "vector"; model?: string };

An embedding generated by putObject from a description has kind: "description". embeddingModel contains embedder.info.name.

Record types

Index records have a type.

Value Meaning
"CREATE" The object was created. Restoring a deleted object also produces this type.
"UPDATE_METADATA" Metadata was updated. Renaming also produces this type.
"DELETE" The object was logically deleted.

You can filter by MetadataFilter.recordType, but deleted records are always excluded from listings.

IndexedObject

Search results are OmnioObject plus a score.

type IndexedObject<TUserMetadata = Record<string, unknown>> = OmnioObject<TUserMetadata> & {
  score?: number;
};

The meaning of the score depends on the similarity metric. For cosine similarity, larger is closer. For L2 distance, the score is a negative distance.

Working with OmnioKey

OmnioObject.key is an OmnioKey, not a string. Use key.key when you need the string. JSON.stringify serializes it as a string.

const object = await omnio.headObject("notes/a.txt");

console.log(object?.key.key); // notes/a.txt
console.log(JSON.stringify(object?.key)); // "notes/a.txt"

Next steps

Was this page helpful?