跳转至

TypeScript OSDK

This page provides generic documentation for the TypeScript OSDK based on an example Restaurant object and its associated actions and queries. You can use Developer Console in the platform to generate documentation based on your specific Ontology.

Property API name Type
Restaurant Id (primary key) restaurantId String
Restaurant Name (title) restaurantName String
Address address String
Email eMail String
Number Of Reviews numberOfReviews Integer
Phone Number phoneNumber String
Review Summary reviewSummary String
Date Of Opening dateOfOpening LocalDate

Load single Restaurant

Parameters:

  • primaryKey string: The primary key of the Restaurant you want to fetch

Example query:

const result: Osdk.Instance<Restaurant> = await client(Restaurant).fetchOne(
  "primaryKey",
);

Example API response:

{
  "$primaryKey": "Restaurant Id",
  "$apiName": "Restaurant",
  "eMail": "Email",
  "restaurantId": "Restaurant Id",
  "address": "Address",
  "reviewSummary": "Review Summary",
  "phoneNumber": "Phone Number",
  "numberOfReviews": 123,
  "restaurantName": "Restaurant Name"
}

Load a page of Restaurants

Load a page of objects. This automatically loads a single page of objects based on the specified page size.

Note that this endpoint leverages the underlying object syncing technology used for the object type. If Restaurant is backed by Object Storage V2, there is no request limit. If Restaurant is backed by Object Storage V1 (Phonograph), there is a limit of 10,000 results; if more than 10,000 Restaurants have been requested, an ObjectsExceededLimit error will be thrown.

Example query:

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

Example API response:

{
  "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"
    }
    // ... Rest of page
  ]
}

Load all Restaurants

Loads all Restaurant objects into an array. This uses an async iterator to fetch all objects across multiple pages.

Note that this endpoint leverages the underlying object syncing technology used for the object type. If Restaurant is backed by Object Storage V2, there is no request limit. If Restaurant is backed by Object Storage V1 (Phonograph), there is a limit of 10,000 results; if more than 10,000 Restaurants have been requested, an ObjectsExceededLimit error will be thrown.

Example query:

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;
}

// If Array.fromAsync() is available in your target environment
function getAllFromAsync(): Promise<Array<Osdk.Instance<Restaurant>>> {
  return Array.fromAsync(client(Restaurant).asyncIter());
}

Example API response:

{
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "eMail": "Email",
      "restaurantId": "Restaurant Id",
      "address": "Address",
      "reviewSummary": "Review Summary",
      "phoneNumber": "Phone Number",
      "numberOfReviews": 123,
      "restaurantName": "Restaurant Name"
    }
    // ... Rest of data
  ]
}

Load ordered results

Load an ordered page of Restaurants by specifying a sort direction for specific properties. When calling via APIs, sorting criteria are specified via the fields array. When calling via SDKs, you can specify ordering via the $orderBy parameter in the fetch options. The sort order for strings is case-sensitive, meaning numbers will come before uppercase letters, which will come before lowercase letters. For example, Cat will come before bat.

Parameters:

  • $orderBy Record<string, "asc" | "desc">: An object specifying the property you want to order by and the direction ("asc" for ascending or "desc" for descending).

Example query:

const page: PageResult<Osdk.Instance<Restaurant>> = await client(Restaurant)
  .fetchPage({
    $orderBy: { restaurantName: "asc" },
    $pageSize: 30,
  });

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Object A",
      "$apiName": "Restaurant",
      "restaurantName": "A"
      // ...Rest of properties
    },
    {
      "$primaryKey": "Object B",
      "$apiName": "Restaurant",
      "restaurantName": "B"
      // ...Rest of properties
    }
    // ... Rest of page
  ]
}

Filtering

The types of filtering you can perform depend on the types of the properties on a given object type. These filters can also be combined together via Boolean expressions to construct more complex filters.

Note that this endpoint leverages the underlying object syncing technology used for the object type. If Restaurant is backed by Object Storage V2, there is no request limit. If Restaurant is backed by Object Storage V1 (Phonograph), there is a limit of 10,000 results; if more than 10,000 Restaurants have been requested, an ObjectsExceededLimit error will be thrown.

Parameters:

  • where WhereClause (optional): Filter on a particular property. The possible operations depend on the type of the property. Filters are specified as an object with property names as keys and filter operators as values.
  • $orderBy OrderBy (optional): Order the results based on a particular property. You can chain the .where() call with fetchPage() and pass $orderBy in the options to achieve the same result.

Example query:

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

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": null
      // ... Rest of properties
    }
    // ... Rest of page
  ]
}

Types of search filters

Starts with

Only applies to String properties. Searches for Restaurants where restaurantName starts with the given string (case insensitive).

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • $startsWith string: Value to use for prefix matching against Restaurant Name. For example, "foo" will match "foobar" but not "barfoo".

Example query:

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

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foobar"
      // ... Rest of properties
    }
  ]
}

Contains any terms

Only applies to String properties. Returns Restaurants where restaurantName contains any of the white-space separated words (case insensitive) in any order in the provided value.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • $containsAnyTerm string: White-space separated set of words to match on. For example, "foo bar" will match "bar baz" but not "baz qux".

Example query:

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

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foo bar baz"
      // ... Rest of properties
    },
    {
      "$primaryKey": "Restaurant Id 2",
      "$apiName": "Restaurant",
      "restaurantName": "bar baz"
      // ... Rest of properties
    }
  ]
}

Contains all terms

Only applies to String properties. Returns Restaurants where restaurantName contains all the white-space separated words (case insensitive) in any order in the provided value.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • $containsAllTerms string: White-space separated set of words to match on. For example, "foo bar" will match "hello foo baz bar" but not "foo qux".

Example query:

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

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "hello foo baz bar"
      // ... Rest of properties
    }
  ]
}

Contains all terms in order

Only applies to String properties. Returns Restaurants where restaurantName contains all the terms (case insensitive) in the order provided and are adjacent to each other.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • $containsAllTermsInOrder string: White-space separated set of words to match on. For example, "foo bar" will match "hello foo bar baz" but not "bar foo qux".

Example query:

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

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foo bar baz"
      // ... Rest of properties
    }
  ]
}

Range comparison

Only applies to Numeric, String and DateTime properties. Returns Restaurants where Restaurant.restaurantName is less than a value.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • value string | number | date: Value to compare Restaurant Name to

Comparison types:

  • Less than $lt
  • Greater than $gt
  • Less than or equal to $lte
  • Greater than or equal to $gte

Example query:

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

Equal to

Only applies to Boolean, DateTime, Numeric, and String properties. Searches for Restaurants where restaurantName equals the given value.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • $eq string | number | boolean | date: Value to do an equality check with Restaurant Name.

Example query:

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

Example API response:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "Restaurant Name"
      // ... Rest of properties
    }
  ]
}

Null check

Only applies to Array, Boolean, DateTime, Numeric, and String properties. Searches for Restaurants based on whether a value for restaurantName exists or not.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • $isNull boolean: Whether Restaurant Name exists. For checking that fields are non-null, use $not filter with $isNull: true.

Example query:

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

Not filter

Returns Restaurants where the query is not satisfied. This can be further combined with other boolean filter operations.

Parameters:

  • $not: The search query to invert.

Example query:

const restaurantObjectSet = client(Restaurant)
  .where({
    $not: { restaurantName: { $isNull: true } },
  });

And filter

Returns Restaurants where all queries are satisfied. This can be further combined with other boolean filter operations.

Parameters:

  • $and Filter[]: The set of search queries to and together.

Example query:

const restaurantObjectSet = client(Restaurant)
  .where({
    $and: [
      { $not: { restaurantName: { $isNull: true } } },
      { restaurantName: { $eq: "<primarykey>" } },
    ],
  });

Or filter

Returns Restaurants where any of the specified queries are satisfied. This can be further combined with other Boolean filter operations.

Parameters:

  • $or Filter[]: The set of search queries to or together.

Example query:

const restaurantObjectSet = client(Restaurant)
  .where({
    $or: [
      { $not: { restaurantName: { $isNull: true } } },
      { restaurantName: { $eq: "<primarykey>" } },
    ],
  });

Aggregations

Aggregations allow you to compute summary statistics over a set of data. They are useful for understanding patterns and insights from large datasets without having to manually analyze each individual data point. You can combine multiple aggregation operations to create more complex queries that provide deeper insights into the data.

Note that this endpoint leverages the underlying object syncing technology used for the object type. If Restaurant is backed by Object Storage V2, there is no request limit. If Restaurant is backed by Object Storage V1 (Phonograph), there is a limit of 10,000 results; if more than 10,000 Restaurants have been requested, an ObjectsExceededLimit error will be thrown.

Perform aggregations on Restaurants.

Parameters:

  • $select: Set of aggregation functions to perform.
  • $groupBy (optional): A set of groupings to create for aggregation results
  • where (optional): Filter on a particular property. The possible operations depend on the type of the property.

Example query:

const numRestaurants = await client(Restaurant)
  .where({ restaurantName: { $isNull: false } })
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { restaurantName: "exact" },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {
            "restaurantName": "Restaurant Name"
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

Types of aggregations

Approximate distinct

Computes an approximate number of distinct values for restaurantName.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • name string (optional): Alias for the computed count. By default, this is distinctCount.

Example query:

const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: { restaurantName: { $approximateDistinct: "unordered" } },
  });

// This is equivalent to the above, but uses a custom metric name
const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: {
      metricName: { restaurantName: { $approximateDistinct: "unordered" } },
    },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {},
        metrics: [
            {
                name: "distinctCount",
                value: 100
            }
        ]
    }]
}

Count

Computes the total count of Restaurants.

Parameters:

  • name string (optional): Alias for the computed count. By default, this is count.

Example query:

const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {},
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

Numeric aggregations

Only applies to numeric properties. Calculate the maximum, minimum, sum, or average of a numeric property for Restaurants.

Parameters:

  • field: Name of the property to use (for example, numberOfReviews).
  • name string (optional): An alias for the computed value.

Aggregation types:

  • Average: $avg
  • Maximum: $max
  • Minimum: $min
  • Sum: $sum

Example query:

const avgReviewScore = await client(Restaurant)
  .aggregate({
    $select: { numberOfReviews: { $avg: "unordered" } },
  });

// This is equivalent to the above, but uses a custom metric name
const avgReviewScore = await client(Restaurant)
  .aggregate({
    $select: {
      avgReview: { numberOfReviews: { $avg: "unordered" } },
    },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {},
        metrics: [
            {
                name: "avg",
                value: 100
            }
        ]
    }]
}

Types of group bys

Exact grouping

Groups Restaurants by exact values of restaurantName.

Parameters:

  • field: Name of the property to use (for example, restaurantName).
  • "exact": Specifies exact grouping.

Example query:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { restaurantName: "exact" },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {
            "restaurantName": "Restaurant Name"
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

Numeric bucketing

Groups Restaurants by dividing numberOfReviews into buckets with the specified width.

Parameters:

  • field: Name of the property to use (for example, numberOfReviews).
  • $fixedWidth number: Width of each bucket to divide the selected property into.

Example query:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { numberOfReviews: { $fixedWidth: 10 } },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {
            "restaurantName": "Restaurant Name"
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

Range grouping

Groups Restaurants by specified ranges of numberOfReviews.

Parameters:

  • field: Name of the property to use (for example, numberOfReviews).
  • $ranges Array<{$gte: number, $lt: number}>: Set of ranges which have an inclusive start value and exclusive end value.

Example query:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: {
      numberOfReviews: {
        $ranges: [
          { $gte: 0, $lt: 3 },
          { $gte: 3, $lt: 5 },
        ],
      },
    },
  });

Example API response:

{
  "excludedItems": 0,
  "data": [
    {
      "group": {
        "numberOfReviews": {
          "startValue": 0,
          "endValue": 3
        }
      },
      "metrics": [
        {
          "name": "count",
          "value": 50
        }
      ]
    },
    {
      "group": {
        "numberOfReviews": {
          "startValue": 3,
          "endValue": 5
        }
      },
      "metrics": [
        {
          "name": "count",
          "value": 30
        }
      ]
    }
  ]
}

Datetime grouping

Groups Restaurants by dateOfOpening via buckets of a specific date/time duration.

Parameters:

  • field: Name of the property to use (for example, dateOfOpening).
  • duration value and unit: The duration unit and value to group by.

Duration types:

  • Seconds $duration: "seconds"
  • Minutes $duration: "minutes"
  • Hours $duration: "hours"
  • Days $duration: "days"
  • Weeks $duration: "weeks"
  • Months $duration: "months"
  • Quarters $duration: "quarters"
  • Years $duration: "years"

Example query:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: {
      dateOfOpening: {
        $duration: "days",
        $value: 10,
      },
    },
  });

Example API response:

{
    excludedItems: 0,
    data: [{
        group: {
            "dateOfOpening": {
                startValue: "2024-09-25"
            }
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

Actions on the Ontology

Action types in the Ontology refer to predefined operations that you can perform on objects within your data model. These actions can create, modify, and delete objects in the Ontology. Action types are generated based on the Ontology and can be used within the TypeScript OSDK to perform specific tasks on objects in the code.

Parameters for adding a review to a Restaurant (addRestaurantReview)

Property API name Type
Restaurant Id restaurantId String
Review Rating reviewRating Integer
Review Summary reviewSummary String

Apply action

To apply an action, fill in the input parameter values. This will execute an action and return if the response was valid or invalid.

Parameters:

  • parameters Object: Object of parameter ID to values to use for those input parameters.
  • restaurantId string
  • reviewRating number
  • reviewSummary string
  • options (optional): Options for the action execution.
  • $returnEdits boolean: Whether the edits are returned in the response after the action is applied.

Example query:

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);
}

Example API response:

{
  "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
  }
}

Apply batch action

To apply a batch of actions, fill in the input parameter values. This will execute a series of action and return if the response was valid or invalid. Note that this does not return validations, only edits.

Parameters:

  • parameters Array<Object>: Array of parameter objects with values to use for those input parameters.
  • restaurantId string
  • reviewRating number
  • reviewSummary string
  • options (optional): Options for the action execution.
  • $returnEdits boolean: Whether the edits are returned in the response after the action is applied.

Example query:

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);
}

Example Response:

{
  "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
  }
}

Functions

Functions (sometimes referred to as "functions on objects" or "FOO") in the Palantir platform are a powerful feature designed to enhance data modeling and manipulation. Functions provide a way to define and execute custom logic on the data stored in the Ontology, allowing users to create more sophisticated data transformations, validations, and analytics.

Within the TypeScript SDK, a user can execute Foundry Functions through generated function definitions.

By adding your functions to your application, you can generate code that calls functions on objects to execute logic and get the result.

In this example, we have a function findSimilarRestaurants that takes in an ID and returns an object set containing all the similar Restaurants.

Parameters for executing a function to find similar Restaurants (findSimilarRestaurants)

Property API name Type
Restaurant Id restaurantId String

Returns: RestaurantObjectSet

Apply function

To apply a function, you must execute it via the client. This is done by passing the function to the client and calling executeFunction with the parameters.

Example query:

const result = await client(findSimilarRestaurants).executeFunction({
  restaurantId: "restaurantId",
});

中文翻译

TypeScript OSDK

本页面基于示例 Restaurant 对象及其关联的操作(Action)和查询(Query),提供 TypeScript OSDK 的通用文档。您可以使用平台中的开发者控制台(Developer Console) 根据您的特定本体论(Ontology)生成文档

属性 API 名称 类型
Restaurant Id (主键) restaurantId String
Restaurant Name (标题) restaurantName String
Address address String
Email eMail String
Number Of Reviews numberOfReviews Integer
Phone Number phoneNumber String
Review Summary reviewSummary String
Date Of Opening dateOfOpening LocalDate

加载单个 Restaurant

参数:

  • primaryKey string 要获取的 Restaurant 的主键

示例查询:

const result: Osdk.Instance<Restaurant> = await client(Restaurant).fetchOne(
  "primaryKey",
);

示例 API 响应:

{
  "$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 由对象存储 V2 (Object Storage V2) 支持,则没有请求限制。如果 Restaurant 由对象存储 V1 (Object Storage V1, Phonograph) 支持,则结果限制为 10,000 条;如果请求的 Restaurants 超过 10,000 条,将抛出 ObjectsExceededLimit 错误。

示例查询:

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

示例 API 响应:

{
  "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 对象加载到一个数组中。此操作使用异步迭代器(Async Iterator)跨多个页面获取所有对象。

请注意,此端点利用了该对象类型所使用的底层对象同步技术。如果 Restaurant 由对象存储 V2 (Object Storage V2) 支持,则没有请求限制。如果 Restaurant 由对象存储 V1 (Object Storage V1, Phonograph) 支持,则结果限制为 10,000 条;如果请求的 Restaurants 超过 10,000 条,将抛出 ObjectsExceededLimit 错误。

示例查询:

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 响应:

{
  "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 页面。通过 API 调用时,排序条件通过 fields 数组指定。通过 SDK 调用时,您可以通过获取选项中的 $orderBy 参数指定排序。字符串的排序顺序区分大小写,这意味着数字会排在大写字母之前,大写字母会排在小写字母之前。例如,Cat 会排在 bat 之前。

参数:

  • $orderBy Record<string, "asc" | "desc"> 一个对象,指定要排序的属性以及排序方向("asc" 表示升序,"desc" 表示降序)。

示例查询:

const page: PageResult<Osdk.Instance<Restaurant>> = await client(Restaurant)
  .fetchPage({
    $orderBy: { restaurantName: "asc" },
    $pageSize: 30,
  });

示例 API 响应:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Object A",
      "$apiName": "Restaurant",
      "restaurantName": "A"
      // ...其余属性
    },
    {
      "$primaryKey": "Object B",
      "$apiName": "Restaurant",
      "restaurantName": "B"
      // ...其余属性
    }
    // ... 页面其余部分
  ]
}

过滤(Filtering)

您可以执行的过滤类型取决于给定对象类型上属性的类型。这些过滤器还可以通过布尔表达式(Boolean Expressions)组合在一起,以构建更复杂的过滤器。

请注意,此端点利用了该对象类型所使用的底层对象同步技术。如果 Restaurant 由对象存储 V2 (Object Storage V2) 支持,则没有请求限制。如果 Restaurant 由对象存储 V1 (Object Storage V1, Phonograph) 支持,则结果限制为 10,000 条;如果请求的 Restaurants 超过 10,000 条,将抛出 ObjectsExceededLimit 错误。

参数:

  • where WhereClause(可选): 对特定属性进行过滤。可能的操作取决于属性的类型。过滤器被指定为一个对象,其中属性名作为键,过滤器运算符作为值。
  • $orderBy OrderBy(可选): 基于特定属性对结果进行排序。您可以将 .where() 调用与 fetchPage() 链式调用,并在选项中传递 $orderBy 以达到相同效果。

示例查询:

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

示例 API 响应:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": null
      // ... 其余属性
    }
    // ... 页面其余部分
  ]
}

搜索过滤器类型

开头匹配(Starts with)

仅适用于字符串(String)属性。搜索 restaurantName 以给定字符串开头的 Restaurants(不区分大小写)。

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • $startsWith string 用于与 Restaurant Name 进行前缀匹配的值。例如,"foo" 将匹配 "foobar",但不匹配 "barfoo"。

示例查询:

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

示例 API 响应:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foobar"
      // ... 其余属性
    }
  ]
}

包含任意词(Contains any terms)

仅适用于字符串(String)属性。返回 restaurantName 包含提供的值中任意一个以空格分隔的词(不区分大小写,顺序不限)的 Restaurants

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • $containsAnyTerm string 要匹配的以空格分隔的词集。例如,"foo bar" 将匹配 "bar baz",但不匹配 "baz qux"。

示例查询:

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

示例 API 响应:

{
  "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"
      // ... 其余属性
    }
  ]
}

包含所有词(Contains all terms)

仅适用于字符串(String)属性。返回 restaurantName 包含提供的值中所有以空格分隔的词(不区分大小写,顺序不限)的 Restaurants

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • $containsAllTerms string 要匹配的以空格分隔的词集。例如,"foo bar" 将匹配 "hello foo baz bar",但不匹配 "foo qux"。

示例查询:

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

示例 API 响应:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "hello foo baz bar"
      // ... 其余属性
    }
  ]
}

按顺序包含所有词(Contains all terms in order)

仅适用于字符串(String)属性。返回 restaurantName 包含所有按提供顺序排列且相邻的词(不区分大小写)的 Restaurants

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • $containsAllTermsInOrder string 要匹配的以空格分隔的词集。例如,"foo bar" 将匹配 "hello foo bar baz",但不匹配 "bar foo qux"。

示例查询:

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

示例 API 响应:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "foo bar baz"
      // ... 其余属性
    }
  ]
}

范围比较(Range comparison)

仅适用于数值(Numeric)、字符串(String)和日期时间(DateTime)属性。返回 Restaurant.restaurantName 小于某个值的 Restaurants

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • value string | number | date 要与 Restaurant Name 进行比较的值

比较类型:

  • 小于 $lt
  • 大于 $gt
  • 小于或等于 $lte
  • 大于或等于 $gte

示例查询:

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

等于(Equal to)

仅适用于布尔(Boolean)、日期时间(DateTime)、数值(Numeric)和字符串(String)属性。搜索 restaurantName 等于给定值的 Restaurants

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • $eq string | number | boolean | date 用于与 Restaurant Name 进行相等性检查的值。

示例查询:

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

示例 API 响应:

{
  "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
  "data": [
    {
      "$primaryKey": "Restaurant Id",
      "$apiName": "Restaurant",
      "restaurantName": "Restaurant Name"
      // ... 其余属性
    }
  ]
}

空值检查(Null check)

仅适用于数组(Array)、布尔(Boolean)、日期时间(DateTime)、数值(Numeric)和字符串(String)属性。根据 restaurantName 的值是否存在来搜索 Restaurants

参数:

  • field:要使用的属性名称(例如,restaurantName)。
  • $isNull booleanRestaurant Name 是否存在。要检查字段非空,请使用 $not 过滤器配合 $isNull: true

示例查询:

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

Not 过滤器

返回不满足查询条件的 Restaurants。这可以进一步与其他布尔过滤器操作组合使用。

参数:

  • $not:要反转的搜索查询。

示例查询:

const restaurantObjectSet = client(Restaurant)
  .where({
    $not: { restaurantName: { $isNull: true } },
  });

And 过滤器

返回满足所有查询条件的 Restaurants。这可以进一步与其他布尔过滤器操作组合使用。

参数:

  • $and Filter[]:要进行 and 运算的一组搜索查询。

示例查询:

const restaurantObjectSet = client(Restaurant)
  .where({
    $and: [
      { $not: { restaurantName: { $isNull: true } } },
      { restaurantName: { $eq: "<primarykey>" } },
    ],
  });

Or 过滤器

返回满足任意指定查询条件的 Restaurants。这可以进一步与其他布尔过滤器操作组合使用。

参数:

  • $or Filter[]:要进行 or 运算的一组搜索查询。

示例查询:

const restaurantObjectSet = client(Restaurant)
  .where({
    $or: [
      { $not: { restaurantName: { $isNull: true } } },
      { restaurantName: { $eq: "<primarykey>" } },
    ],
  });

聚合(Aggregations)

聚合允许您计算一组数据的汇总统计信息。它们有助于理解大型数据集中的模式和洞察,而无需手动分析每个单独的数据点。您可以组合多个聚合操作来创建更复杂的查询,从而提供对数据的更深入洞察。

请注意,此端点利用了该对象类型所使用的底层对象同步技术。如果 Restaurant 由对象存储 V2 (Object Storage V2) 支持,则没有请求限制。如果 Restaurant 由对象存储 V1 (Object Storage V1, Phonograph) 支持,则结果限制为 10,000 条;如果请求的 Restaurants 超过 10,000 条,将抛出 ObjectsExceededLimit 错误。

Restaurants 执行聚合。

参数:

  • $select: 要执行的聚合函数集。
  • $groupBy(可选): 为聚合结果创建的一组分组。
  • where(可选): 对特定属性进行过滤。可能的操作取决于属性的类型。

示例查询:

const numRestaurants = await client(Restaurant)
  .where({ restaurantName: { $isNull: false } })
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { restaurantName: "exact" },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {
            "restaurantName": "Restaurant Name"
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

聚合类型

近似去重(Approximate distinct)

计算 restaurantName 的近似去重值数量。

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • name string(可选): 计算计数的别名。默认情况下,此值为 distinctCount

示例查询:

const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: { restaurantName: { $approximateDistinct: "unordered" } },
  });

// 这与上述等效,但使用了自定义指标名称
const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: {
      metricName: { restaurantName: { $approximateDistinct: "unordered" } },
    },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {},
        metrics: [
            {
                name: "distinctCount",
                value: 100
            }
        ]
    }]
}

计数(Count)

计算 Restaurants 的总数。

参数:

  • name string(可选): 计算计数的别名。默认情况下,此值为 count

示例查询:

const distinctRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {},
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

数值聚合(Numeric aggregations)

仅适用于数值(Numeric)属性。计算 Restaurants 的数值属性的最大值、最小值、总和或平均值。

参数:

  • field: 要使用的属性名称(例如,numberOfReviews)。
  • name string(可选): 计算值的别名。

聚合类型:

  • 平均值:$avg
  • 最大值:$max
  • 最小值:$min
  • 总和:$sum

示例查询:

const avgReviewScore = await client(Restaurant)
  .aggregate({
    $select: { numberOfReviews: { $avg: "unordered" } },
  });

// 这与上述等效,但使用了自定义指标名称
const avgReviewScore = await client(Restaurant)
  .aggregate({
    $select: {
      avgReview: { numberOfReviews: { $avg: "unordered" } },
    },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {},
        metrics: [
            {
                name: "avg",
                value: 100
            }
        ]
    }]
}

分组类型

精确分组(Exact grouping)

restaurantName 的精确值对 Restaurants 进行分组。

参数:

  • field: 要使用的属性名称(例如,restaurantName)。
  • "exact": 指定精确分组。

示例查询:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { restaurantName: "exact" },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {
            "restaurantName": "Restaurant Name"
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

数值分桶(Numeric bucketing)

通过将 numberOfReviews 划分为指定宽度的桶来对 Restaurants 进行分组。

参数:

  • field: 要使用的属性名称(例如,numberOfReviews)。
  • $fixedWidth number 将所选属性划分成的每个桶的宽度。

示例查询:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: { numberOfReviews: { $fixedWidth: 10 } },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {
            "restaurantName": "Restaurant Name"
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

范围分组(Range grouping)

按指定的 numberOfReviews 范围对 Restaurants 进行分组。

参数:

  • field: 要使用的属性名称(例如,numberOfReviews)。
  • $ranges Array<{$gte: number, $lt: number}> 一组范围,每个范围包含一个包含起始值和一个排除结束值。

示例查询:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: {
      numberOfReviews: {
        $ranges: [
          { $gte: 0, $lt: 3 },
          { $gte: 3, $lt: 5 },
        ],
      },
    },
  });

示例 API 响应:

{
  "excludedItems": 0,
  "data": [
    {
      "group": {
        "numberOfReviews": {
          "startValue": 0,
          "endValue": 3
        }
      },
      "metrics": [
        {
          "name": "count",
          "value": 50
        }
      ]
    },
    {
      "group": {
        "numberOfReviews": {
          "startValue": 3,
          "endValue": 5
        }
      },
      "metrics": [
        {
          "name": "count",
          "value": 30
        }
      ]
    }
  ]
}

日期时间分组(Datetime grouping)

通过特定日期/时间持续时间的桶按 dateOfOpeningRestaurants 进行分组。

参数:

  • field: 要使用的属性名称(例如,dateOfOpening)。
  • duration value and unit: 用于分组的时间持续单位及其值。

持续时间类型:

  • $duration: "seconds"
  • 分钟 $duration: "minutes"
  • 小时 $duration: "hours"
  • $duration: "days"
  • $duration: "weeks"
  • $duration: "months"
  • 季度 $duration: "quarters"
  • $duration: "years"

示例查询:

const groupedRestaurants = await client(Restaurant)
  .aggregate({
    $select: { $count: "unordered" },
    $groupBy: {
      dateOfOpening: {
        $duration: "days",
        $value: 10,
      },
    },
  });

示例 API 响应:

{
    excludedItems: 0,
    data: [{
        group: {
            "dateOfOpening": {
                startValue: "2024-09-25"
            }
        },
        metrics: [
            {
                name: "count",
                value: 100
            }
        ]
    }]
}

本体论上的操作(Actions on the Ontology)

本体论中的操作类型(Action types)指的是您可以在数据模型中的对象上执行的预定义操作。这些操作可以创建、修改和删除本体论中的对象。操作类型是基于本体论生成的,可以在 TypeScript OSDK 中使用,以在代码中对对象执行特定任务。

Restaurant 添加评论的参数 (addRestaurantReview)

属性 API 名称 类型
Restaurant Id restaurantId String
Review Rating reviewRating Integer
Review Summary reviewSummary String

应用操作(Apply action)

要应用操作,请填写输入参数值。这将执行一个操作并返回响应是有效还是无效。

参数:

  • parameters Object 参数 ID 到这些输入参数值的对象。
  • restaurantId string
  • reviewRating number
  • reviewSummary string
  • options(可选): 操作执行的选项。
  • $returnEdits boolean 是否在应用操作后在响应中返回编辑内容。

示例查询:

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 响应:

{
  "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
  }
}

批量应用操作(Apply batch action)

要应用一批操作,请填写输入参数值。这将执行一系列操作并返回响应是有效还是无效。请注意,这不返回验证信息,只返回编辑内容。

参数:

  • parameters Array<Object> 参数对象数组,包含这些输入参数的值。
  • restaurantId string
  • reviewRating number
  • reviewSummary string
  • options(可选): 操作执行的选项。
  • $returnEdits boolean 是否在应用操作后在响应中返回编辑内容。

示例查询:

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);
}

示例响应:

{
  "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
  }
}

函数(Functions)

Palantir 平台中的函数(有时称为"对象上的函数"或"FOO")是一项强大的功能,旨在增强数据建模和操作。函数提供了一种定义和执行存储在本体论中数据的自定义逻辑的方法,允许用户创建更复杂的数据转换、验证和分析。

在 TypeScript SDK 中,用户可以通过生成的函数定义来执行 Foundry 函数。

通过将函数添加到您的应用程序,您可以生成调用对象上的函数来执行逻辑并获取结果的代码。

在此示例中,我们有一个函数 findSimilarRestaurants,它接受一个 ID 并返回一个包含所有相似 Restaurants 的对象集(Object Set)。

执行查找相似 Restaurants 函数的参数 (findSimilarRestaurants)

属性 API 名称 类型
Restaurant Id restaurantId String

返回:RestaurantObjectSet

应用函数(Apply function)

要应用函数,您必须通过客户端执行它。这是通过将函数传递给客户端并调用 executeFunction 并传入参数来完成的。

示例查询:

const result = await client(findSimilarRestaurants).executeFunction({
  restaurantId: "restaurantId",
});