---
title: アーキテクチャ
description: Omnio-js を構成するエンティティストレージ、インデックス、埋め込み器の役割と処理の流れを説明します。
---

## 3 つの層 [#three-layers]

Omnio は、役割の異なる 3 つの部品を組み合わせます。

| 層           | インターフェース | 責務                                                     |
| ------------ | ---------------- | -------------------------------------------------------- |
| エンティティ | `IOmnioEntity`   | バイト列を `entityId` ごとに保存します。                 |
| インデックス | `IObjectIndex`   | キー、メタデータ、タグ、埋め込み、削除予約を保存します。 |
| 埋め込み     | `IEmbedder`      | テキストや画像を `Float32Array` に変換します。           |

この分離により、バイト列の保存先とメタデータの検索基盤を独立して選べます。たとえば、バイト列はローカルのファイル、インデックスは PostgreSQL に置けます。

## 書き込みの流れ [#write-path]

`putObject` は次の順序で処理します。

1. 入力を検証し、キーを `OmnioKey` に変換します。
2. データをバイト列に変換します。
3. 説明文があり、埋め込みを無効にしていなければ、埋め込みを生成します。
4. 同じキーの既存レコードをインデックスから取得します。
5. 新しい `entityId` を発行し、物理削除の予約をインデックスに記録します。
6. バイト列をエンティティストレージに保存し、SHA-256 を取得します。
7. メタデータとハッシュをインデックスに保存します。
8. 不要になった物理削除の予約を削除します。

手順 5 で先に予約を記録するのは、手順 6 と 7 の間でクラッシュしても、参照されないバイト列を後から回収できるようにするためです。

## 読み取りの流れ [#read-path]

`headObject` と `listObjects` はインデックスだけを参照します。エンティティストレージは読みません。

`getObject` と `streamObject` は、最初にインデックスから `entityId` とハッシュを取得し、次にエンティティストレージからバイト列を読みます。インデックスにレコードがあるのにバイト列がない場合は `EntityMissingError` です。

## 検索の流れ [#search-path]

`searchObjects` は次の順序で処理します。

1. クエリーを埋め込みます。テキストか画像のクエリーでは `IEmbedder` を使います。
2. インデックスの `search` を呼び出します。
3. インデックスは `filter` を適用し、dirty と削除済みの行を除外します。
4. 埋め込みの類似度を計算し、スコアの降順で返します。
5. `includeEmbedding: false` の場合は結果から埋め込みを除きます。

テキストと画像のクエリーでは、現在の埋め込み器のモデル名に一致する行だけを対象にします。これにより、異なるモデルのベクトルが混ざるのを防ぎます。

## バックグラウンド処理 [#background-tasks]

`open()` は次の処理をバックグラウンドで開始します。

- **削除の回収**: 猶予期間を過ぎた削除済みバイト列を物理削除します。
- **予約の回収**: クラッシュなどで残った物理削除予約を処理します。
- **再インデックス**: モデルや次元数が変わったオブジェクトの埋め込みを作り直します。

バックグラウンド処理は読み取りを待たせません。検索は、その時点で完了している行だけを対象にします。

## ロック [#locks]

Omnio は `asyncmux` を使い、ライフサイクルと操作の同時実行を制御します。

- `open` と `close` は排他ロックを取ります。
- 通常の操作は共有ロックを取り、互いに並行して実行できます。
- 同じキーへの書き込みは、キー単位の排他ロックで直列化します。
- 複数のキーを扱う操作は、キーを並べ替えてロックし、デッドロックを防ぎます。

SQL インデックスも、読み取りは共有ロック、書き込みは排他ロックを使います。

## なぜ分離するのか [#why-separate]

- バイト列の保存には、ファイルシステム、OPFS、クラウドストレージなど、用途に合った仕組みを使えます。
- メタデータ検索には、SQL データベースの絞り込みやトランザクションを使えます。
- 埋め込みモデルは、精度、速度、対応モダリティーに応じて交換できます。

それぞれの責務を明確にすることで、テスト用のメモリー構成から本番の PostgreSQL 構成まで、同じ API で扱えます。

## 次に読む [#next]

- [一貫性とライフサイクル](/omnio-js/explanation/consistency-and-lifecycle)
- [意味検索の仕組み](/omnio-js/explanation/semantic-search)
