コンテンツにスキップ
Omnio-js
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

Omnio クラス

Omnio のコンストラクター、プロパティ、公開メソッドのリファレンスです。

概要

Omnio は、エンティティストレージ、インデックス、埋め込み器をまとめ、外部に API を提供するクラスです。

import { Omnio } from "omnio";

const omnio = new Omnio({
  entity,
  index,
  embedder,
});

await omnio.open();

すべてのメソッドには、入力オブジェクトの signal か最後の引数で AbortSignal を渡せます。close() はライフサイクルシグナルを通じて、実行中の操作を中断します。

コンストラクター

new Omnio(options: OmnioOptions)
オプション 型 必須 説明
entity IOmnioEntityBuilder はい persist() まで構成した unikvs ビルダーです。
index IObjectIndex はい メタデータとベクトルのインデックスです。
embedder IEmbedder はい 埋め込みを生成する部品です。
purgeGracePeriodMs number いいえ バイト列を物理削除するまでの猶予時間です。既定値は 60000 です。

コンストラクターは entity.build() を実行し、チェックサム用のミドルウェアを注入します。入力は valibot で検証され、不正な値には ValiError が投げられます。

プロパティ

isOpen

readonly isOpen: boolean

エンティティストレージとインデックスの両方が開いているとき true です。

ライフサイクル

open

open(signal?: AbortSignal): Promise<void>

エンティティストレージとインデックスを開きます。インデックスを開くとマイグレーションが適用され、埋め込みモデルや次元数が変わったオブジェクトに dirty フラグが立ちます。

すでに開いているときは何もしません。signal を省略すると 30 秒でタイムアウトします。

close

close(signal?: AbortSignal): Promise<void>

実行中の操作を中断し、バックグラウンド処理の完了を待ってから、インデックスとエンティティストレージを閉じます。

signal を省略すると 30 秒でタイムアウトします。インデックスかエンティティストレージを閉じるのに失敗すると例外を投げますが、次回の close() で再試行できます。

オブジェクトの書き込み

putObject

putObject<TUserMetadata>(input: PutObjectInput<TUserMetadata>): Promise<OmnioObject<TUserMetadata>>

オブジェクトを保存します。同じキーが存在する場合は上書きします。

入力 型 必須 既定値
key string | OmnioKey はい -
data Uint8Array | Blob | ReadableStream<Uint8Array> はい -
contentType string はい -
description string いいえ -
tags readonly string[] いいえ []
userMetadata TUserMetadata いいえ {}
embedding Float32Array いいえ -
embed boolean いいえ true
signal AbortSignal いいえ -

description があり、embedding がなく、embed が false でない場合、説明文の埋め込みを生成します。

上書き時も新しい entityId を割り当てます。createdAt は既存の値を引き継ぎ、updatedAt は現在時刻に更新します。

copyObject

copyObject<TUserMetadata>(
  sourceKey: string | OmnioKey,
  destinationKey: string | OmnioKey,
  signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>

バイト列とメタデータを複製します。複製先には新しい entityId を割り当てます。複製先が存在すれば上書きし、作成時刻は引き継ぎます。

複製元が存在しない場合は null を返します。同じキーを指定した場合は元のオブジェクトを返します。

renameObject

renameObject<TUserMetadata>(
  sourceKey: string | OmnioKey,
  destinationKey: string | OmnioKey,
  signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>

キーを変更します。オブジェクトのバイト列は移動せず、同じ entityId を維持します。変更先が存在すれば上書きし、元の変更先のバイト列はバックグラウンドで削除されます。

変更元が存在しない場合は null を返します。同じキーを指定した場合は元のオブジェクトを返します。

updateObjectMetadata

updateObjectMetadata<TUserMetadata>(
  input: UpdateObjectMetadataInput<TUserMetadata>,
): Promise<OmnioObject<TUserMetadata> | null>

変更可能なメタデータだけを更新します。キーが存在しなければ null を返します。

入力 型 説明
key string | OmnioKey 更新するキーです。
contentType string 省略時は変更しません。
description string 省略時は変更しません。
tags readonly string[] 省略時は変更しません。空配列を渡すとすべて削除します。
userMetadata TUserMetadata 省略時は変更しません。
signal AbortSignal 中断シグナルです。

サイズ、ハッシュ、作成時刻、entityId、埋め込みは更新できません。説明文を変更しても埋め込みは作り直されません。

オブジェクトの読み取り

getObject

getObject(key: string | OmnioKey, signal?: AbortSignal): Promise<Uint8Array | null>

オブジェクトのバイト列を返します。削除済みか存在しない場合は null を返します。

インデックスに hashAlgorithm: "sha256" が記録されている場合は、返す前にチェックサムを検証します。インデックスにレコードがあるのにバイト列がない場合は EntityMissingError を投げます。

streamObject

streamObject(
  key: string | OmnioKey,
  signal?: AbortSignal,
): Promise<IValueStream<Uint8Array> | null>

オブジェクトをストリームで返します。削除済みか存在しない場合は null を返します。

チェックサムはストリームの終端で検証されます。途中でキャンセルしたり、最後まで読み取らなかった場合は検証されません。取得したストリームは呼び出し側で破棄してください。

headObject

headObject<TUserMetadata>(
  key: string | OmnioKey,
  signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>

headObject<TUserMetadata, const TSelect extends HeadObjectSelect>(
  key: string | OmnioKey,
  options: HeadObjectOptions<TSelect>,
): Promise<Pick<OmnioObject<TUserMetadata>, SelectedHeadObjectField<TSelect>> | null>

メタデータを返します。キーが存在しなければ null を返します。

select を省略するとすべての項目を返します。指定すると、true にした項目だけを返します。

const head = await omnio.headObject("notes/a.txt", {
  select: { key: true, size: true, tags: true },
});

hasObject

hasObject(key: string | OmnioKey, signal?: AbortSignal): Promise<boolean>

インデックスにメタデータが存在するかを返します。エンティティストレージは参照しません。削除済みの場合は false です。

listObjects

listObjects<TUserMetadata>(
  options?: {
    limit?: number;
    cursor?: string | null;
    filter?: MetadataFilter;
  },
  signal?: AbortSignal,
): Promise<IObjectIndex.ListResult<TUserMetadata>>

削除されていないオブジェクトをキーの昇順で返します。既定の件数は 100 件です。nextCursor が null でなければ、次の呼び出しに渡してください。

type ListResult<TUserMetadata> = {
  items: readonly OmnioObject<TUserMetadata>[];
  nextCursor: string | null;
};

searchObjects

searchObjects<TUserMetadata>(
  input: SearchObjectsInput,
): Promise<IndexedObject<TUserMetadata>[]>

意味検索をして、結果をスコアの降順で返します。

入力 型 既定値
query { text } | { image, mimeType? } | { vector } -
topK number 20
minScore number -
filter MetadataFilter -
includeEmbedding boolean true
signal AbortSignal -

query.text と query.image は現在の埋め込み器で埋め込みます。対象になるのは、embedder.info.name に一致する保存済みベクトルだけです。query.vector ではモデル名で絞り込みません。

searchObjects はインデックスの既定の類似度計算を使うので、コサイン類似度で検索します。L2 距離を使うときは IObjectIndex.search を直接呼び出してください。

deleteObject

deleteObject(key: string | OmnioKey, signal?: AbortSignal): Promise<boolean>

論理削除します。削除フラグを立てたら true、キーが存在しなければ false を返します。

バイト列は purgeGracePeriodMs の後にバックグラウンドで物理削除されます。

再インデックス

reindexObject

reindexObject<TUserMetadata>(
  key: string | OmnioKey,
  signal?: AbortSignal,
): Promise<OmnioObject<TUserMetadata> | null>

現在の埋め込み器で説明文の埋め込みを作り直します。キーが存在しなければ null を返します。説明文がなければ何も変更せず、現在のオブジェクトを返します。

中断とタイムアウト

  • open と close は、シグナルを省略すると 30 秒でタイムアウトします。
  • それ以外のメソッドは、呼び出し側のシグナルと close 時のライフサイクルシグナルをまとめて使います。
  • 中断された操作は OperationAbortedError など、シグナルの理由で失敗します。

次に読む

このページは役に立ちましたか?