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"