---
title: Object model
description: Reference for OmnioObject fields, mutable metadata, and record types.
---

## `OmnioObject` [#omnio-object]

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

```ts
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 [#entity-derived]

`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 [#mutable-metadata]

```ts
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 [#embedding-source]

```ts
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 [#record-type]

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` [#indexed-object]

Search results are `OmnioObject` plus a `score`.

```ts
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` [#key-type]

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

```ts
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 [#next]

- [Object keys](/omnio-js/en/reference/object-keys)
- [Metadata filters](/omnio-js/en/reference/metadata-filter)
