TypeScript オントロジー SDK

このページでは、Restaurant オブジェクトの例と、それに関連するアクションおよびクエリに基づいて、TypeScript オントロジー SDK の汎用的なドキュメントを提供します。プラットフォームの Developer Console を使用して、お使いのオントロジーに基づくドキュメントを生成できます。

このページの例は、TypeScript オントロジー SDK 2.x を対象としています。1.x からアップグレードする場合は、TypeScript オントロジー SDK 移行ガイドで構文の変更を確認してください。集計に記載されている集計の変更も含まれます。バージョン別のドキュメントは、プラットフォームの Developer Console でも利用可能です。

単一の Restaurant を読み込む

パラメーター：

• primaryKey string： 取得する Restaurant の主キー

クエリの例：

Copied!
1
2
3
const result: Osdk.Instance<Restaurant> = await client(Restaurant).fetchOne(
  "primaryKey",
);

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
  "$primaryKey": "Restaurant Id",
  "$apiName": "Restaurant",
  "eMail": "Email",
  "restaurantId": "Restaurant Id",
  "address": "Address",
  "reviewSummary": "Review Summary",
  "phoneNumber": "Phone Number",
  "numberOfReviews": 123,
  "restaurantName": "Restaurant Name"
}

Restaurants の1ページを読み込む

オブジェクトの1ページを読み込みます。指定したページサイズに基づいて、オブジェクトの1ページが自動的に読み込まれます。

このエンドポイントは、オブジェクトタイプで使用されている基盤のオブジェクト同期技術を利用します。Restaurant が Object Storage v2 を使用している場合、リクエストに上限はありません。Restaurant が Object Storage v1（Phonograph）を使用している場合、結果の上限は10,000件です。10,000個を超える Restaurants がリクエストされた場合、ObjectsExceededLimit エラーがスローされます。

クエリの例：

Copied!
1
2
const page: PageResult<Osdk.Instance<Restaurant>> = await client(Restaurant)
  .fetchPage({ $pageSize: 30 });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "eMail": "Email",
      "restaurantId": "Restaurant Id",
      "address": "Address",
      "reviewSummary": "Review Summary",
      "phoneNumber": "Phone Number",
      "numberOfReviews": 123,
      "restaurantName": "Restaurant Name"
    }
    // ... ページの残り
  ]
}

すべての Restaurants を読み込む

すべての Restaurant オブジェクトを配列に読み込みます。非同期イテレーターを使用して、複数のページにわたるすべてのオブジェクトを取得します。

このエンドポイントは、オブジェクトタイプで使用されている基盤のオブジェクト同期技術を利用します。Restaurant が Object Storage v2 を使用している場合、リクエストに上限はありません。Restaurant が Object Storage v1（Phonograph）を使用している場合、結果の上限は10,000件です。10,000個を超える Restaurants がリクエストされた場合、ObjectsExceededLimit エラーがスローされます。

クエリの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
async function getAll(): Promise<Array<Osdk.Instance<Restaurant>>> {
  const objects: Osdk.Instance<Restaurant>[] = [];
  for await (const obj of client(Restaurant).asyncIter()) {
    objects.push(obj);
  }
  return objects;
}

// 対象環境で Array.fromAsync() が利用可能な場合
function getAllFromAsync(): Promise<Array<Osdk.Instance<Restaurant>>> {
  return Array.fromAsync(client(Restaurant).asyncIter());
}

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "eMail": "Email",
      "restaurantId": "Restaurant Id",
      "address": "Address",
      "reviewSummary": "Review Summary",
      "phoneNumber": "Phone Number",
      "numberOfReviews": 123,
      "restaurantName": "Restaurant Name"
    }
    // ... データの残り
  ]
}

並べ替えた結果を読み込む

特定のプロパティの並べ替え方向を指定して、並べ替えた Restaurants の1ページを読み込みます。API 経由で呼び出す場合、並べ替え条件は fields 配列で指定します。SDK 経由で呼び出す場合、取得オプションの $orderBy パラメーターで並び順を指定できます。文字列の並べ替え順序は大文字と小文字を区別するため、数字、大文字、小文字の順になります。たとえば、Cat は bat より前になります。

パラメーター：

• $orderBy Record<string, "asc" | "desc">： 並べ替えに使用するプロパティと方向（昇順の場合は "asc"、降順の場合は "desc"）を指定するオブジェクトです。

クエリの例：

Copied!
1
2
3
4
5
const page: PageResult<Osdk.Instance<Restaurant>> = await client(Restaurant)
  .fetchPage({
    $orderBy: { restaurantName: "asc" },
    $pageSize: 30,
  });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Object A",
      "$apiName": "Restaurant",
      "restaurantName": "A"
      // ...残りのプロパティ
    },
    {
      "$primaryKey": "Object B",
      "$apiName": "Restaurant",
      "restaurantName": "B"
      // ...残りのプロパティ
    }
    // ... ページの残り
  ]
}

リンク

オブジェクトタイプに定義された各リンクタイプは、オブジェクトのインスタンスの $link コンテナ内に、リンクのAPI名をキーとするエントリーを生成します。このエントリーの形式は、リンクの多重度によって異なります。

• 多重度が単一のリンクでは、SingleLinkAccessor が生成され、fetchOne() と fetchOneWithErrors() が公開されます。
• 多重度が多のリンクでは、リンク先のタイプの ObjectSet が生成されるため、ほかのオブジェクトセットと同じメソッドがサポートされます。

以下の例では、Restaurant に多重度が単一の city リンクと、多重度が多の reviews リンクがあることを前提としています。お使いのオントロジーのリンクのAPI名に置き換えてください。

オブジェクトのインスタンスから多重度が単一のリンクを読み取るクエリの例：

Copied!
1
2
3
4
5
6
7
const restaurant = await client(Restaurant).fetchOne("primaryKey");

const city = await restaurant.$link.city.fetchOne();

// fetchOneWithErrors は例外をスローする代わりに { value } または { error } を返します。
// リンクされたオブジェクトが存在しない場合も、その他の失敗の場合も、{ error } として返されます。
const cityResult = await restaurant.$link.city.fetchOneWithErrors();

多重度が多のリンクをオブジェクトセットとして読み取るクエリの例：

Copied!
1
2
3
4
5
6
7
const restaurant = await client(Restaurant).fetchOne("primaryKey");

const reviews = await restaurant.$link.reviews.fetchPage({ $pageSize: 30 });

for await (const review of restaurant.$link.reviews.asyncIter()) {
  // ...
}

単一のオブジェクトのインスタンスではなく、オブジェクトセットからリンクをたどるには、リンクのAPI名を指定して pivotTo() を呼び出します。リンク先のタイプのオブジェクトセットが返されるため、リンクをたどる操作を連鎖させたり、フィルターや集計と組み合わせたりできます。

Copied!
1
2
3
const reviewsForNamedRestaurants = client(Restaurant)
  .where({ restaurantName: { $isNull: false } })
  .pivotTo("reviews");

フィルタリング

実行できるフィルタリングの種類は、対象のオブジェクトタイプのプロパティのデータ型によって異なります。これらのフィルターは、ブール式を使って組み合わせることで、より複雑なフィルターを構成することもできます。

このエンドポイントは、オブジェクトタイプに使用されている基盤のオブジェクト同期技術を利用します。Restaurant が Object Storage v2 を使用している場合、リクエストに上限はありません。Restaurant が Object Storage v1（Phonograph）を使用している場合、結果の上限は10,000件です。10,000個を超える Restaurants がリクエストされた場合、ObjectsExceededLimit エラーがスローされます。

パラメーター：

• where WhereClause（任意）： 特定のプロパティで絞り込みます。使用できる操作は、プロパティのデータ型によって異なります。フィルターは、プロパティ名をキー、フィルター演算子を値とするオブジェクトとして指定します。
• $orderBy OrderBy（任意）： 特定のプロパティに基づいて結果を並べ替えます。.where() の呼び出しに fetchPage() をチェーンし、オプションに $orderBy を渡すことでも、同じ結果を得られます。

クエリの例：

Copied!
1
2
3
const page: PageResult<Osdk.Instance<Restaurant>> = await client(Restaurant)
  .where({ restaurantName: { $isNull: true } })
  .fetchPage({ $pageSize: 30 });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": null
      // ... 残りのプロパティ
    }
    // ... ページの残り
  ]
}

検索フィルターの種類

次で始まる

文字列プロパティにのみ適用されます。restaurantName が指定された文字列で始まる Restaurants を検索します（大文字と小文字は区別しません）。

パラメーター：

• フィールド： 使用するプロパティの名前（例：restaurantName）。
• $startsWith string： Restaurant Name との接頭辞一致に使用する値。たとえば、「foo」は「foobar」に一致しますが、「barfoo」には一致しません。

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $startsWith: "foo" } });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foobar"
      // ... 残りのプロパティ
    }
  ]
}

いずれかの語句を含む

文字列プロパティにのみ適用されます。指定された値に含まれる空白で区切られた単語のいずれかを、restaurantName が任意の順序で含む Restaurants を返します（大文字と小文字は区別しません）。

パラメーター：

• フィールド： 使用するプロパティの名前（例：restaurantName）。
• $containsAnyTerm string： 一致対象となる、空白で区切られた単語の集合。たとえば、「foo bar」は「bar baz」に一致しますが、「baz qux」には一致しません。

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $containsAnyTerm: "foo bar" } });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foo bar baz"
      // ... 残りのプロパティ
    },
    {
      "$primaryKey": "Restaurant Id 2",
      "$apiName": "Restaurant",
      "restaurantName": "bar baz"
      // ... 残りのプロパティ
    }
  ]
}

すべての語句を含む

文字列プロパティにのみ適用されます。指定された値に含まれる空白で区切られた単語のすべてを、restaurantName が任意の順序で含む Restaurants を返します（大文字と小文字は区別しません）。

パラメーター：

• フィールド： 使用するプロパティの名前（例：restaurantName）。
• $containsAllTerms string： 一致対象となる、空白で区切られた単語の集合。たとえば、「foo bar」は「hello foo baz bar」に一致しますが、「foo qux」には一致しません。

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $containsAllTerms: "foo bar" } });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "hello foo baz bar"
      // ... 残りのプロパティ
    }
  ]
}

すべての語句を順序どおりに含む

文字列プロパティにのみ適用されます。restaurantName がすべての語句を指定された順序で、互いに隣接した形で含む Restaurants を返します（大文字と小文字は区別しません）。

パラメーター：

• フィールド： 使用するプロパティの名前（例：restaurantName）。
• $containsAllTermsInOrder string： 一致対象となる、空白で区切られた単語の集合。たとえば、「foo bar」は「hello foo bar baz」に一致しますが、「bar foo qux」には一致しません。

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $containsAllTermsInOrder: "foo bar" } });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foo bar baz"
      // ... 残りのプロパティ
    }
  ]
}

範囲比較

数値、文字列、および DateTime プロパティにのみ適用されます。Restaurant.restaurantName が指定した値より小さい Restaurants を返します。

パラメーター：

• フィールド： 使用するプロパティの名前（例：restaurantName）。
• 値 string | number | date： Restaurant Name と比較する値

比較の種類：

• より小さい $lt
• より大きい $gt
• 以下 $lte
• 以上 $gte

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $lt: "Restaurant Name" } });

次と等しい

ブール値、DateTime、数値、および文字列プロパティにのみ適用されます。restaurantName が指定された値と等しい Restaurants を検索します。

パラメーター：

• フィールド： 使用するプロパティの名前（例：restaurantName）。
• $eq string | number | boolean | date： Restaurant Name との等価性のチェックに使用する値。

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $eq: "Restaurant Name" } });

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "Restaurant Name"
      // ... 残りのプロパティ
    }
  ]
}

null チェック

配列、ブール値、DateTime、数値、および文字列プロパティにのみ適用されます。restaurantName の値が存在するかどうかに基づいて Restaurants を検索します。

パラメーター：

• field：使用するプロパティの名前（例：restaurantName）。
• $isNull boolean：Restaurant Name が存在するかどうか。フィールドが null でないことを確認するには、$not フィルターと $isNull: true を使用します。

クエリの例：

Copied!
1
2
const restaurantObjectSet = client(Restaurant)
  .where({ restaurantName: { $isNull: true } });

Not フィルター

クエリを満たさない Restaurants を返します。ほかのブールフィルター操作とさらに組み合わせることもできます。

パラメーター：

• $not：反転させる検索クエリ。

クエリの例：

Copied!
1
2
3
4
const restaurantObjectSet = client(Restaurant)
  .where({
    $not: { restaurantName: { $isNull: true } },
  });

And フィルター

すべてのクエリを満たす Restaurants を返します。ほかのブールフィルター操作とさらに組み合わせることもできます。

パラメーター：

• $and Filter[]：and で結合する検索クエリの集合。

クエリの例：

Copied!
1
2
3
4
5
6
7
const restaurantObjectSet = client(Restaurant)
  .where({
    $and: [
      { $not: { restaurantName: { $isNull: true } } },
      { restaurantName: { $eq: "<primarykey>" } },
    ],
  });

Or フィルター

指定されたクエリのいずれかを満たす Restaurants を返します。ほかのブールフィルター操作とさらに組み合わせることもできます。

パラメーター：

• $or Filter[]：or で結合する検索クエリの集合。

クエリの例：

Copied!
1
2
3
4
5
6
7
const restaurantObjectSet = client(Restaurant)
  .where({
    $or: [
      { $not: { restaurantName: { $isNull: true } } },
      { restaurantName: { $eq: "<primarykey>" } },
    ],
  });

集合演算

同じオブジェクトタイプのオブジェクトセットを組み合わせることができます。各メソッドは1個以上のオブジェクトセットを受け取り、新しいオブジェクトセットを返すため、呼び出しをチェーンできます。

• union() は、指定されたオブジェクトセットのいずれかに存在するオブジェクトを返します。
• intersect() は、指定されたすべてのオブジェクトセットに存在するオブジェクトを返します。
• subtract() は、指定されたオブジェクトセットに存在するオブジェクトを除外します。

Copied!
1
2
3
4
5
6
const highlyReviewed = client(Restaurant).where({ numberOfReviews: { $gte: 100 } });
const named = client(Restaurant).where({ restaurantName: { $isNull: false } });

const either = highlyReviewed.union(named);
const both = highlyReviewed.intersect(named);
const onlyHighlyReviewed = highlyReviewed.subtract(named);

最近傍

ベクトルプロパティを持つオブジェクトタイプでは、nearestNeighbors() によってオブジェクトセットを最も近い一致に絞り込みます。以下の例では、Restaurant に embedding という名前のベクトルプロパティがあることを前提としています。

パラメーター：

• query string | number[]： プロパティに定義された埋め込みモデルに対応するベクトル、または自動的に埋め込みに変換されるテキスト。
• numNeighbors number： 返すオブジェクトの数。1 <= numNeighbors <= 500 の範囲に制限されます。オブジェクトタイプに含まれるオブジェクトがこの数より少ない場合、すべてのオブジェクトが返されます。
• property： 検索対象となる、埋め込みモデルが定義されたプロパティのキー。

Copied!
1
2
3
const similar = await client(Restaurant)
  .nearestNeighbors("coffee", 5, "embedding")
  .fetchPage();

上記の例は、最も近い5個の Restaurants を返しますが、順序は保証されません。関連度順に並べ替え、各オブジェクトの $score を含めるには、fetchPage() に $orderBy: "relevance" を渡します。

集計

集計では、データの概要統計量を計算できます。個々のデータポイントを手動で分析することなく、大規模なデータセットからパターンやインサイトを把握するのに役立ちます。複数の集計操作を組み合わせて、データに関するより深いインサイトを得られる複雑なクエリを作成できます。

このエンドポイントは、オブジェクトタイプと同じオブジェクト同期技術を使用します。Restaurant は Object Storage v2 または Object Storage v1 (Phonograph) に基づくことができ、いずれの場合も、エンドポイントは最大10,000件の結果を返します。10,000個を超える Restaurants をリクエストすると、エンドポイントは ObjectsExceededLimit エラーを返します。

Restaurants に対して集計を実行します。

パラメーター：

• $select: 実行する集計関数。
• $groupBy（任意）: 集計結果に対して作成するグループ化。

aggregate() が受け付けるオプションは、この2つだけです。集計対象のオブジェクトを絞り込むには、以下に示すように、.aggregate() を呼び出す前にオブジェクトセットに .where() 呼び出しを連結します。

以下の結果と記されたブロックは、生の HTTP レスポンスではなく、TypeScript で aggregate() が解決する値を示しています。上記のオブジェクト読み込みエンドポイントとは異なり、集計ではこの2つが異なります。

クエリの例：

Copied!
1
2
3
4
5
6
const numRestaurants = await client(Restaurant)
  .where({ restaurantName: { $isNull: false } })
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { restaurantName: "exact" },
  });

結果：

Copied!
1
2
3
4
// numRestaurants: Array<{ $group: { restaurantName: string }; $count: number }>
[
  { $group: { restaurantName: "Restaurant Name" }, $count: 100 },
]

グループ化された集計は行の配列を返し、一致するオブジェクトがない場合は空の配列になります。読み取る前に、インデックスの存在を確認してください。numRestaurants[0]?.$group.restaurantName でグループの値を、numRestaurants[0]?.$count でメトリクスを取得できます。グループ化されていない集計は、配列ではなく単一のオブジェクトを返します。

集計の種類

プロパティで利用可能なメトリクスは、そのプロパティのデータ型によって異なります。

• すべてのプロパティタイプ：approximateDistinct と exactDistinct。
• 数値型のプロパティ：sum、avg、min、max、approximateDistinct、exactDistinct。
• 日付およびタイムスタンプのプロパティ：min、max、approximateDistinct、exactDistinct。これらのデータ型では、sum と avg のメトリクスは利用できません。

"restaurantName:avg" のように、プロパティタイプが対応していないメトリクスをリクエストすると、型エラーになります。このチェックはプロパティのベースタイプを使用し、配列値のプロパティを考慮しないため、配列プロパティでリクエストされたメトリクスはコンパイルできますが、実行時に失敗する可能性があります。

近似一意数

restaurantName の一意な値の近似数を計算します。

パラメーター：

• "<property>:approximateDistinct": プロパティのAPI名とメトリクスをコロンで結合した単一の文字列キー（例："restaurantName:approximateDistinct"）。値はメトリクスの並べ替え方向で、この例では "unordered" です。

TypeScript オントロジー SDK はプロパティとメトリクスから結果のキーを導出するため、メトリクスにカスタム名を付けることはできません。Python オントロジー SDK では、計算されたメトリクスにエイリアスを付ける name パラメーターが説明されています。

クエリの例：

Copied!
1
2
3
4
const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: { "restaurantName:approximateDistinct": "unordered" },
  });

結果：

Copied!
1
2
// distinctRestaurants: { restaurantName: { approximateDistinct: number } }
{ restaurantName: { approximateDistinct: 100 } }

distinctRestaurants.restaurantName.approximateDistinct で値を読み取ります。approximateDistinct と exactDistinct はどちらも、件数を数えるプロパティのデータ型や、そのプロパティが必須かどうかにかかわらず、| undefined を含まない number 型になります。

件数

Restaurants の合計件数を計算します。

パラメーター：

• $count: $ 接頭辞が付き、プロパティを指定しない唯一のセレクターキーです。値はメトリクスの並べ替え方向で、この例では "unordered" です。

クエリの例：

Copied!
1
2
3
4
const restaurantCount = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
  });

結果：

Copied!
1
2
// restaurantCount: { $count: number }
{ $count: 100 }

restaurantCount.$count で値を読み取ります。$count キーは常に number 型であり、選択した場合にのみ結果に含まれます。

数値集計

Restaurants のプロパティの最大値、最小値、合計、平均を計算します。sum と avg のメトリクスは、数値型のプロパティにのみ適用されます。集計の種類に記載されているとおり、min と max は日付およびタイムスタンプのプロパティにも適用されます。

パラメーター：

• "<property>:<metric>": プロパティのAPI名とメトリクスをコロンで結合した単一の文字列キー（例："numberOfReviews:avg"）。値はメトリクスの並べ替え方向で、この例では "unordered" です。

集計の種類：

• 平均：avg
• 最大値：max
• 最小値：min
• 合計：sum

これらのメトリクスには $ 接頭辞がなく、$count が $ 接頭辞を持つ唯一のセレクターキーです。近似一意数と同様に、結果のキーはプロパティとメトリクスから導出されるため、TypeScript オントロジー SDK ではメトリクスのエイリアスを利用できません。

クエリの例：

Copied!
1
2
3
4
const avgReviewScore = await client(Restaurant)
  .aggregate({
    $select: { "numberOfReviews:avg": "unordered" },
  });

結果：

Copied!
1
2
3
// numberOfReviews が任意の場合、avg には | undefined が含まれます。
// avgReviewScore: { numberOfReviews: { avg: number | undefined } }
{ numberOfReviews: { avg: 4.2 } }

avgReviewScore.numberOfReviews.avg で値を読み取ります。2つの一意数メトリクスとは異なり、sum、avg、min、max のデータ型は元のプロパティ自体の値の種類となり、そのプロパティが必須かどうかも反映されます。そのため、任意の Integer プロパティでは、avg は number | undefined になります。上記の例では、numberOfReviews がこの条件に該当することを想定しています。オントロジー SDK での値の種類が文字列であるプロパティは、代わりに文字列を返します。上のテーブルの LocalDate プロパティでは、"dateOfOpening:max" は string | undefined 型になります。Long、Decimal、タイムスタンプのプロパティに対するメトリクスも同様です。undefined の場合を処理してください。集計に一致するオブジェクトがない場合、avg、min、max は undefined になります。

1回の呼び出しで複数のメトリクスをリクエストするには、それぞれのキーを追加します。

クエリの例：

Copied!
1
2
3
4
5
6
7
8
9
const stats = await client(Restaurant)
  .aggregate({
    $select: {
      $count: "unordered",
      "numberOfReviews:avg": "unordered",
      "numberOfReviews:max": "unordered",
      "restaurantName:exactDistinct": "unordered",
    },
  });

結果：

Copied!
1
2
3
4
5
6
7
8
9
10
// stats: {
//   $count: number;
//   numberOfReviews: { avg: number | undefined; max: number | undefined };
//   restaurantName: { exactDistinct: number };
// }
{
  $count: 100,
  numberOfReviews: { avg: 4.2, max: 123 },
  restaurantName: { exactDistinct: 87 },
}

このような呼び出しに $groupBy を追加すると、結果は行の配列に変わります。各メトリクスは、行内の $group の中ではなく、$group と並んで配置されます。

Copied!
1
2
3
4
5
// Array<{
//   $group: { restaurantName: string };
//   $count: number;
//   numberOfReviews: { avg: number | undefined; max: number | undefined };
// }>

グループ化の種類

完全一致によるグループ化

restaurantName の値の完全一致で Restaurants をグループ化します。

パラメーター：

• プロパティキー： グループ化に使用するプロパティのAPI名で、$groupBy のキーとして使用します（たとえば、restaurantName）。
• "exact"： そのキーの値で、完全一致によるグループ化を指定します。

クエリの例：

Copied!
1
2
3
4
5
const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { restaurantName: "exact" },
  });

結果：

Copied!
1
2
3
4
// groupedRestaurants: Array<{ $group: { restaurantName: string }; $count: number }>
[
  { $group: { restaurantName: "Restaurant Name" }, $count: 100 },
]

数値のバケット化

numberOfReviews を指定した幅のバケットに分割して、Restaurants をグループ化します。

パラメーター：

• プロパティキー： グループ化に使用するプロパティのAPI名で、$groupBy のキーとして使用します（たとえば、numberOfReviews）。
• $fixedWidth number： 選択したプロパティを分割する各バケットの幅です。

クエリの例：

Copied!
1
2
3
4
5
const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { numberOfReviews: { $fixedWidth: 10 } },
  });

結果：

Copied!
1
2
3
4
5
// groupedRestaurants: Array<{ $group: { numberOfReviews: number }; $count: number }>
[
  { $group: { numberOfReviews: 0 }, $count: 100 },
  { $group: { numberOfReviews: 10 }, $count: 40 },
]

各固定幅グループは、そのバケットの開始値を表す単純な値として返されます。

範囲によるグループ化

numberOfReviews の指定した範囲で Restaurants をグループ化します。

パラメーター：

• プロパティキー： グループ化に使用するプロパティのAPI名で、$groupBy のキーとして使用します（たとえば、numberOfReviews）。
• $ranges Array<[number, number]>： 範囲の集合です。各範囲は2要素の [start, end] タプルで記述し、開始値を含み、終了値を含みません。両方の境界値が必須のため、片側の境界がない範囲は表現できません。

範囲は日付およびタイムスタンプのプロパティにも適用でき、その場合、各境界値は ISO 8601 文字列です。日付プロパティには $ranges: [["2024-01-02", "2024-01-09"]] のように日付のみを指定し、タイムスタンププロパティには $ranges: [["2024-01-02T00:00:00Z", "2024-01-09T00:00:00Z"]] のように完全なタイムスタンプを指定します。

クエリの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: {
      numberOfReviews: {
        $ranges: [
          [0, 3],
          [3, 5],
        ],
      },
    },
  });

結果：

Copied!
1
2
3
4
5
6
7
8
// groupedRestaurants: Array<{
//   $group: { numberOfReviews: { startValue: number; endValue: number } };
//   $count: number;
// }>
[
  { $group: { numberOfReviews: { startValue: 0, endValue: 3 } }, $count: 50 },
  { $group: { numberOfReviews: { startValue: 3, endValue: 5 } }, $count: 30 },
]

範囲によるグループ化だけが、{ startValue, endValue } オブジェクトとして返されます。完全一致、固定幅、および日時によるグループ化では、プロパティ自体の値のデータ型を持つ単純なスカラー値が返されます。固定幅および日時によるグループ化の場合、このスカラー値は、オブジェクトが持つ値ではなく、バケットの開始値です。

日時によるグループ化

特定の日時の期間を表すバケットを使用し、dateOfOpening で Restaurants をグループ化します。

パラメーター：

• プロパティキー： グループ化に使用するプロパティのAPI名で、$groupBy のキーとして使用します（たとえば、dateOfOpening）。
• $duration [value, unit]： 単位の数と単位名からなる2要素のタプルです。

dateOfOpening のような日付プロパティで利用可能な期間の種類：

• 日：[n, "days"]
• 週：[1, "weeks"]
• 月：[1, "months"]
• 四半期：[1, "quarters"]
• 年：[1, "years"]

weeks、months、quarters、years の単位は、値として 1 のみを受け付けます。seconds、minutes、hours、days は任意の数値を受け付けます。1日未満の単位（seconds、minutes、hours）はタイムスタンププロパティでのみ利用可能で、dateOfOpening のような日付プロパティでは利用できません。

クエリの例：

Copied!
1
2
3
4
5
const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { dateOfOpening: { $duration: [10, "days"] } },
  });

結果：

Copied!
1
2
3
4
// groupedRestaurants: Array<{ $group: { dateOfOpening: string }; $count: number }>
[
  { $group: { dateOfOpening: "2024-09-25" }, $count: 100 },
]

オントロジーに対するアクション

オントロジーのアクションタイプとは、データモデル内のオブジェクトに対して実行できる、事前定義された操作を指します。これらのアクションは、オントロジー内のオブジェクトを作成、変更、削除できます。アクションタイプはオントロジーに基づいて生成され、TypeScript オントロジー SDK 内で使用して、コード内のオブジェクトに対して特定のタスクを実行できます。

Restaurant にレビューを追加するためのパラメーター（addRestaurantReview）

アクションを適用する

アクションを適用するには、入力パラメーターの値を入力します。これによりアクションが実行され、レスポンスが有効か無効かが返されます。

パラメーター：

• パラメーター Object： パラメーターIDを、その入力パラメーターに使用する値に対応付けたオブジェクトです。
  • restaurantId string
  • reviewRating number
  • reviewSummary string
• オプション（任意）： アクション実行のオプションです。
  • $returnEdits boolean： アクションの適用後に、編集内容をレスポンスで返すかどうかを指定します。

クエリの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const result = await client(addReview).applyAction(
  {
    restaurantId: "restaurantId",
    reviewRating: 5,
    reviewSummary: "It was great!",
  },
  {
    $returnEdits: true,
  },
);

if (result.type === "edits") {
  console.log("Review added successfully", result);
} else {
  console.log("Review validation failed!", result);
}

API レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "validation": {
    "result": "VALID",
    "submissionCriteria": [],
    "parameters": {
      "restaurantId": {
        "result": "VALID",
        "evaluatedConstraints": [],
        "required": true
      },
      "reviewRating": {
        "result": "VALID",
        "evaluatedConstraints": [],
        "required": true
      },
      "reviewSummary": {
        "result": "VALID",
        "evaluatedConstraints": [],
        "required": true
      }
    }
  },
  "edits": {
    "type": "edits",
    "edits": [
      {
        "type": "modifyObject",
        "primaryKey": "restaurantId1",
        "objectType": "Restaurant"
      }
    ],
    "addedObjectCount": 0,
    "modifiedObjectsCount": 1,
    "deletedObjectsCount": 0,
    "addedLinksCount": 0,
    "deletedLinksCount": 0
  }
}

アクションをバッチで適用する

アクションをバッチで適用するには、入力パラメーターの値を入力します。これにより一連のアクションが実行され、レスポンスが有効か無効かが返されます。レスポンスには編集内容のみが含まれ、検証結果は含まれません。バッチ適用はすべて適用されるか、まったく適用されないかのいずれかです。バッチ内のいずれかのアクションの実行に失敗すると、バッチ内のどの編集内容も適用されません。

パラメーター：

• パラメーター Array<Object>： 入力パラメーターに使用する値を含むパラメーターオブジェクトの配列です。
  • restaurantId string
  • reviewRating number
  • reviewSummary string
• オプション（任意）： アクション実行のオプションです。
  • $returnEdits boolean： アクションの適用後に、編集内容をレスポンスで返すかどうかを指定します。

クエリの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
const result = await client(addReview).batchApplyAction(
  [
    {
      restaurantId: "restaurantId1",
      reviewRating: 5,
      reviewSummary: "It was great!",
    },
    {
      restaurantId: "restaurantId2",
      reviewRating: 4,
      reviewSummary: "Good food but service can improve.",
    },
  ],
  {
    $returnEdits: true,
  },
);

if (result.type === "edits") {
  const updatedObject = result.editedObjectTypes[0];
  console.log("Edited Objects", updatedObject);
}

レスポンスの例：

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "edits": {
    "type": "edits",
    "edits": [
      {
        "type": "modifyObject",
        "primaryKey": "restaurantId1",
        "objectType": "Restaurant"
      },
      {
        "type": "modifyObject",
        "primaryKey": "restaurantId2",
        "objectType": "Restaurant"
      }
    ],
    "addedObjectCount": 0,
    "modifiedObjectsCount": 2,
    "deletedObjectsCount": 0,
    "addedLinksCount": 0,
    "deletedLinksCount": 0
  }
}

関数

Palantir プラットフォームの関数（「functions on objects」または「FOO」と呼ばれることもあります）は、データモデリングとデータ操作を強化するために設計された強力な機能です。関数を使用すると、オントロジーに保存されているデータに対するカスタムロジックを定義して実行でき、より高度なデータ変換、検証、分析を作成できます。

TypeScript SDK 内では、生成された関数定義を通じて Foundry の関数を実行できます。

アプリケーションに関数を追加すると、オブジェクトに対する関数を呼び出してロジックを実行し、結果を取得するコードを生成できます。

この例では、ID を受け取り、類似するすべての Restaurants を含むオブジェクトセットを返す findSimilarRestaurants 関数を使用します。

類似する Restaurants を検索する関数を実行するためのパラメーター（findSimilarRestaurants）

戻り値：RestaurantObjectSet

関数を適用する

関数を適用するには、クライアントを介して実行する必要があります。関数をクライアントに渡し、パラメーターを指定して executeFunction を呼び出します。

クエリの例：

Copied!
1
2
3
const result = await client(findSimilarRestaurants).executeFunction({
  restaurantId: "restaurantId",
});