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 を検索します。

パラメーター：

• 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() が解決される値を示しています。上記のオブジェクト読み込みエンドポイントとは異なり、集計では両者が異なります。

クエリの例：

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 は、件数を数えるプロパティのデータ型や、そのプロパティが必須かどうかにかかわらず、いずれも number 型であり、| undefined は付きません。

件数

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 プラットフォームの関数（「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",
});

シナリオスコープのクライアントを使用する

オントロジー SDK を使用して、オントロジーシナリオを作成し、操作することもできます。シナリオを使用すると、メインのオントロジーを変更せずに What-if 分析を作成できます。シナリオスコープのクライアントを作成するか、RID を指定して既存のシナリオにアタッチします。Foundry は、このクライアントからの呼び出しを、シナリオの分離されたサンドボックスで評価します。

Copied!
1
2
3
4
5
6
7
8
9
import { createScenario, withScenario } from "@osdk/client/unstable-do-not-use";

// 新しいシナリオを作成します。プラットフォームを呼び出すため、非同期で実行されます。
const scenario = await createScenario(client);

// または、RID を指定して既存のシナリオにアタッチします。同期的に実行され、ネットワーク呼び出しは行われません。
const existingScenario = withScenario(client, "ri.actions..scenario.0000-...");

const result = await scenarioClient(Restaurant).fetchOne("primaryKey");

シナリオスコープのクライアントのその他の機能やバージョン要件については、オントロジー SDK でシナリオを使用するを参照してください。