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"
    }
    // ... データの残り
  ]
}

取得オプション

取得オプションを使用して、TypeScript オントロジー SDK が返すプロパティとオブジェクトメタデータを制御します。利用可能なオプションは、取得メソッドによって異なります。

プロパティを選択する

オブジェクトを取得する場合は、プロパティAPI名の配列を $select に渡します。これは、集計に使用する $select オブジェクトとは異なります。取得時に $select を省略すると、オントロジー SDK は、クエリ対象のオブジェクトタイプまたはインターフェースで宣言されたすべてのネイティブプロパティを返します。オントロジー定義の派生プロパティはデフォルトでは返されないため、明示的に含める必要があります。withProperties() で追加された実行時定義の派生プロパティは、$select を省略するとデフォルトで返されます。$select を使用する場合は、それらのAPI名を配列に含めます。

次の例では、標準のオブジェクトメタデータとともに、restaurantId と restaurantName のみを返します。

Copied!
1
2
3
const page = await client(Restaurant).fetchPage({
  $select: ["restaurantId", "restaurantName"],
});

配列プロパティを選択すると、Ontology Manager でプロパティリデューサーが設定されていても、リデューサーが適用されていない完全な値が返されます。ネイティブプロパティとオントロジー定義の派生プロパティにも、同じ動作が適用されます。

プロパティ修飾子を適用する

$applyModifiers を使用して、個々のプロパティが返す表現を変更します。生成されたオントロジー SDK では、各プロパティに使用できる修飾子が、そのオントロジー設定でサポートされているものに制限されます。

• "applyReducers": リデューサーが設定された配列プロパティについて、配列全体ではなく、選択された配列要素を返します。
• "applyMainValue": メイン値が設定された構造体プロパティについて、メイン値のフィールドのみを返します。
• "applyReducersAndExtractMainValue": 両方の機能が設定された構造体配列について、リデューサーで1個の構造体を選択し、そのメイン値のフィールドを返します。

たとえば、Equipment オブジェクトタイプに、null を許容する Date 配列型の maintenanceHistory プロパティがあり、最新の日付を選択するリデューサーが設定されているとします。$applyModifiers を指定せずに $select を使用すると、配列全体が返されます。

Copied!
1
2
3
4
5
6
7
8
const page = await client(Equipment).fetchPage({
  $select: ["equipmentId", "maintenanceHistory"],
});

for (const equipment of page.data) {
  // string[] | undefined
  const fullMaintenanceHistory = equipment.maintenanceHistory;
}

結果：

Copied!
1
2
3
4
{
  "equipmentId": "E-100",
  "maintenanceHistory": ["2024-01-15", "2024-03-22", "2024-11-01"]
}

リデューサーを適用した表現をリクエストするには、プロパティの修飾子を "applyReducers" に設定します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
const page = await client(Equipment).fetchPage({
  $select: ["equipmentId", "maintenanceHistory"],
  $applyModifiers: {
    maintenanceHistory: "applyReducers",
  },
});

for (const equipment of page.data) {
  // string | undefined
  const mostRecentMaintenanceDate = equipment.maintenanceHistory;
}

結果：

Copied!
1
2
3
4
{
  "equipmentId": "E-100",
  "maintenanceHistory": "2024-11-01"
}

リデューサーを適用した結果には、配列全体ではなく、リデューサーによって選択された1個の要素が含まれます。構造体の配列でも、"applyReducers" は同様に、構造体配列全体ではなく、選択された構造体を返します。修飾子を適用しても、保存されたプロパティデータや派生プロパティデータは変更されません。完全な値が必要な場合は、修飾子を省略します。生成される TypeScript のデータ型には、リクエストした表現が反映され、リデューサーを適用すると配列型から配列の要素型に変わります。

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

特定のプロパティの並べ替え方向を指定して、並べ替えた 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名をキーとするエントリを生成します。このエントリの形式は、リンクの多重度によって異なります。

• 多重度が単一のリンクでは、fetchOne() と fetchOneWithErrors() を公開する SingleLinkAccessor が生成されます。
• 多重度が複数のリンクでは、リンク先のタイプの 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 チェック

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

パラメーター：

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

クエリの例：

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"]] のように日付のみを指定し、Timestamp プロパティには $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）は Timestamp プロパティでのみ利用可能で、dateOfOpening などの Date プロパティでは利用できません。

クエリの例：

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

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

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

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

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

戻り値：RestaurantObjectSet

関数を適用する

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

クエリの例：

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