メタデータフィルター
listObjects と searchObjects で使う MetadataFilter の型と条件の意味をまとめています。
概要
MetadataFilter は、一覧と検索の候補を絞り込む条件です。
type MetadataFilter = {
contentType?: string | MetadataFilter.Condition;
createdAt?: string | Date | MetadataFilter.DateCondition;
fullText?: string;
hash?: string | MetadataFilter.Condition;
recordTimestamp?: string | Date | MetadataFilter.DateCondition;
recordType?: RecordType | MetadataFilter.RecordTypeCondition;
size?: number | bigint | MetadataFilter.SizeCondition;
tags?: string | MetadataFilter.TagsCondition;
updatedAt?: string | Date | MetadataFilter.DateCondition;
};
同じフィールドに複数の条件を指定すると、すべてを満たす必要があります。異なるフィールドの条件もすべて組み合わされます。
削除済みのレコードは、条件に関係なく常に除外されます。
文字列の条件
contentType と hash は、文字列を渡すと完全一致として扱います。オブジェクト形式では次の条件を使えます。
type Condition = {
contains?: string;
endsWith?: string;
equals?: string;
in?: readonly string[];
not?: string;
notIn?: readonly string[];
startsWith?: string;
};
| 条件 | 意味 |
|---|---|
equals |
完全一致します。 |
not |
一致しません。 |
in |
いずれかに一致します。空配列はどのオブジェクトにも一致しません。 |
notIn |
いずれにも一致しません。空配列は条件なしとして扱います。 |
contains |
部分一致します。 |
startsWith |
前方一致します。 |
endsWith |
後方一致します。 |
部分一致には SQL の LIKE または ILIKE を使います。% と _ はエスケープされます。
日時の条件
createdAt、updatedAt、recordTimestamp は、文字列か Date を渡すと完全一致として扱います。オブジェクト形式では次の条件を使えます。
type DateCondition = {
equals?: string | Date;
gt?: string | Date;
gte?: string | Date;
in?: string | Date | readonly (string | Date)[];
lt?: string | Date;
lte?: string | Date;
not?: string | Date;
notIn?: string | Date | readonly (string | Date)[];
};
日時は ISO 8601 形式で指定します。Date を渡した場合は ISO 8601 文字列に正規化されます。削除済みレコードは条件を適用する前に除外されます。また、削除済みレコードの作成時刻と更新時刻は null です。
サイズの条件
size は、数値か bigint を渡すと完全一致として扱います。オブジェクト形式では次の条件を使えます。
type SizeCondition = {
equals?: number | bigint;
gt?: number | bigint;
gte?: number | bigint;
in?: number | bigint | readonly (number | bigint)[];
lt?: number | bigint;
lte?: number | bigint;
not?: number | bigint | readonly (number | bigint)[];
notIn?: readonly (number | bigint)[];
};
タグの条件
tags は、文字列を渡すとそのタグを含むオブジェクトに絞り込みます。オブジェクト形式では次の条件を使えます。
type TagsCondition = {
equals?: readonly string[];
has?: string;
hasEvery?: readonly string[];
hasSome?: readonly string[];
isEmpty?: boolean;
};
| 条件 | 意味 |
|---|---|
has |
指定したタグを含みます。 |
hasEvery |
指定したタグをすべて含みます。 |
hasSome |
指定したタグのいずれかを含みます。空配列はどのオブジェクトにも一致しません。 |
equals |
タグ一覧が一致します。順序は問いません。空配列はタグなしを意味します。 |
isEmpty |
true でタグなし、false でタグありを意味します。 |
レコードタイプの条件
recordType は "CREATE"、"UPDATE_METADATA"、"DELETE" のいずれかか、次の条件です。
type RecordTypeCondition = {
in?: RecordType | readonly RecordType[];
not?: RecordType | readonly RecordType[];
};
削除済みレコードは常に除外されるため、"DELETE" を指定しても結果は空です。
全文検索
fullText は説明文とキーを連結した文字列に対する部分一致です。
await omnio.listObjects({
filter: { fullText: "夕日" },
});
- 単語に分割したり、語幹をそろえたり、順位を付けたりはしません。
- 空文字は条件なしとして扱います。
- 大文字と小文字の区別はデータベースに依存します。SQLite は ASCII の範囲で区別せず、PostgreSQL は
ILIKEを使います。
使用例
const filter: MetadataFilter = {
contentType: { startsWith: "image/" },
createdAt: { gte: new Date("2026-01-01T00:00:00Z") },
size: { lte: 10 * 1024 * 1024 },
tags: { hasEvery: ["public", "2026"] },
recordType: "CREATE",
};