Java OSDK¶

This page provides generic documentation for the Java 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
`E Mail`	`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:

Restaurant result = client.ontology().objects().Restaurant().fetch("primaryKey").orElseThrow();

Example API response:

{
    "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
    "__primaryKey": "Restaurant Id",
    "eMail": "E Mail",
    "restaurantId": "Restaurant Id",
    "address": "Address",
    "reviewSummary": "Review Summary",
    "phoneNumber": "Phone Number",
    "numberOfReviews": 123,
    "restaurantName": "Restaurant Name"
}

Load a stream of `Restaurants`¶

Load a stream of objects that can be collected. This automatically loads pages of objects depending on how many objects are streamed by the user.

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:

Stream<Restaurant> result = client.ontology().objects().Restaurant().fetchStream()

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "eMail": "E Mail",
            "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 a list.

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:

List<Restaurant> result = client.ontology().objects().Restaurant().fetchStream().toList()

Example API response:

{
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "eMail": "E Mail",
            "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 list 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 chain multiple orderBy calls together. 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:

ordering {ObjectType}Ordering: The property you want to order by. With the Java SDK, this is provided for you via a {ObjectType}Ordering interface.
property name and direction ASC| DESC : The direction you want to sort in, either ascending or descending. With the Java SDK, this is provided via the {PROPERTY_NAME}_ASC and {PROPERTY_NAME}_DESC qualifiers on the {ObjectType}Ordering interface.

Example query:

Stream<Restaurant> result = client.ontology()
    .objects()
    .Restaurant()
    .orderBy(RestaurantOrdering.RESTAURANT_NAME_ASC)
    .fetchStream();

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Object A",
            "restaurantName": "A"
            // ...Rest of properties
        },
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Object B",
            "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 Filter (optional): Filter on a particular property. The possible operations depend on the type of the property. This is represented through {ObjectType}Filter with methods to call for each property.
orderBy OrderBy (optional): Order the results based on a particular property. If using the SDK, you can chain the .where call with an orderBy call to achieve the same result. This is represented through {ObjectType}OrderBy with methods to call for each property.

Example query:

List<Restaurant> result = client.ontology()
    .objects()
    .Restaurant()
    .where(RestaurantFilter.restaurantName().isNull(false))
    .fetchStream()
    .toList();

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": null
            // ... Rest of properties
        }
        // ... Rest of page
    ]
}

Types of search filters (`RestaurantFilter`)¶

Starts with¶

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

Parameters:

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

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Restaurant()
    .where(RestaurantFilter.restaurantName().startsWith("foo"));

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": "foobar"
            // ... Rest of properties
        }
    ]
}

Contains any terms¶

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

Parameters:

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

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.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",
            "restaurantName": "foo bar baz"
            // ... Rest of properties
        },
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000001",
            "restaurantName": "bar baz"
            // ... Rest of properties
        }
    ]
}

Contains all terms¶

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

Parameters:

field method: Name of the property to use (for example, restaurantName).
value 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:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().containsAllTerms("foo bar"));

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "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 in the order provided (case insensitive), but they do have to be adjacent to each other.

Parameters:

field method: Name of the property to use (for example, restaurantName).
value 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:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().containsAllTermsInOrder("foo bar"));

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "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 method: Name of the property to use (for example, restaurantName).
value string: 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:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.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 method: Name of the property to use (for example, restaurantName).
value string: Value to do an equality check with Restaurant Name.

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().eq("Restaurant Name"));

Example API response:

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "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 method: Name of the property to use (for example, restaurantName).
value boolean: Whether Restaurant Name exists. Note for the TypeScript SDK, you will need to use a not filter for checking that fields are non-null.

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().isNull(true));

`Not` filter¶

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

Parameters:

value Filter: The search query to invert.

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(
        RestaurantFilter.$not(
            RestaurantFilter.restaurantName().isNull(true)
        )
    );

`And` filter¶

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

Parameters:

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

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(
        RestaurantFilter.$and(
            RestaurantFilter.restaurantName().isNull(false),
            RestaurantFilter.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:

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

Example query:

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(
        RestaurantFilter.$or(
            RestaurantFilter.restaurantName().isNull(false),
            RestaurantFilter.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:

aggregation Aggregation[] (optional): Set of aggregation functions to perform. With the SDK, aggregation computations can be chained together with further searches using .where.
groupBy GroupBy[] (optional): A set of groupings to create for aggregation results
where Filter (optional): Filter on a particular property. The possible operations depend on the type of the property.

Example query:

AggregationResponse numRestaurants = client.ontology()
        .objects()
        .Restaurants()
        .where(RestaurantFilter.restaurantName().isNull(false))
        .groupBy(GroupBy.exact(Restaurant.Property.restaurantName()))
        .count()
        .compute();

Example API response:

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

Types of aggregations (`Aggregation`)¶

Approximate distinct¶

Computes an approximate number of distinct values for restaurantName.

Parameters:

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

Example query:

Double distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .approximateDistinct(Restaurant.Property.restaurantName())
        .compute();

// This is equivalent to the above, but uses metricName as the metric name instead of the default "distinctCount"

AggregationResponse distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .aggregate(
            Map.of(
                "metricName",
                Aggregation.approximateDistinct(Restaurant.Property.restaurantName())
            )
        )
        .compute();

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:

Double distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .count()
        .compute();

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 NumericProperty: 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:

Double avgReviewScore = client.ontology()
        .objects()
        .Restaurant()
        .avg(Restaurant.Property.numberOfReviews())
        .compute();

// This is equivalent to the above, but uses avgReview as the metric name instead of the default "avg"

AggregationResponse distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .aggregate(
            Map.of(
                "avgReview",
                Aggregation.avg(Restaurant.Property.numberOfReviews())
            )
        )
        .compute();

Example API response:

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

Types of group bys (`GroupBy`)¶

Exact grouping¶

Groups Restaurants by exact values of restaurantName.

Parameters:

field Property: Name of the property to use (for example, restaurantName).
maxGroupCount integer (optional): Maximum number of groupings of restaurantName to create.

Example query:

AggregationResponse groupedRestaurants = client.ontology()
       .objects()
       .Restaurant()
       .groupBy(GroupBy.exact(Restaurant.Property.restaurantName()))
       .count()
       .compute();

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 NumericProperty: Name of the property to use (for example, numberOfReviews).
fixedWidth integer (optional): Width of each bucket to divide the selected property into.

Example query:

AggregationResponse groupedRestaurants = client.ontology()
       .objects()
       .Restaurant()
       .groupBy(GroupBy.fixedWidth(Restaurant.Property.numberOfReviews(), 10))
       .count()
       .compute();

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 NumericProperty | DateProperty | TimestampProperty: Name of the property to use (for example, numberOfReviews).
ranges AggregationRange[] (optional): Set of ranges which have an inclusive start value and exclusive end value.

Example query:

AggregationResponse groupedRestaurants = client.ontology()
    .objects()
    .Restaurant()
    .groupBy(
        GroupBy.range(
            Restaurant.Property.numberOfReviews(),
            List.of(
                AggregationRange.of(0, 3),
                AggregationRange.of(3, 5)
            )
        )
    )
    .count()
    .compute();

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 DateProperty | TimestampProperty: Name of the property to use (for example, dateOfOpening).
value integer (optional): The number of duration units to group by.

Duration types:

Seconds bySeconds()
Minutes byMinutes()
Hours byHours()
Days byDays()
Weeks byWeeks()
Months byMonths()
Quarters byQuarters()
Years byYears()

Example query:

AggregationResponse groupedRestaurants = client.ontology()
       .objects()
       .Restaurant()
       .groupBy(GroupBy.byDays(Restaurant.Property.dateOfOpening(), 10))
       .count()
       .compute();

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 Java 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: Map of parameter ID to values to use for those input parameters.
restaurantId string
reviewRating integer
reviewSummary string
options integer (optional): The number of duration units to group by.

Example Query:

AddReviewActionResponse response = client.ontology()
    .actions()
    .addReview()
    .apply(
        AddReviewActionRequest.builder()
            .restaurantId(restaurantId)
            .reviewRating(5)
            .reviewSummary("It was great!")
            .build(),
        ReturnEditsMode.ALL
    );

response.getValidationResult().accept(new ActionValidationVisitor<Object>() {
    @Override
    public Object valid(ActionValidationResponse response) {
        System.out.println("Review added successfully " + response);
        return null;
    }

    @Override
    public Object invalid(ActionValidationResponse response) {
        System.out.println("Review validation failed! " + response);
        return null;
    }
});

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 Object: Map of parameter ID to values to use for those input parameters.
restaurantId string
reviewRating integer
reviewSummary string
value ReturnEditsMode.(ALL|NONE) (optional): Whether the edits are returned in the response after the action is applied.

Example Query:

AddReviewBatchActionResponse response = client.ontology()
    .actions()
    .addReview()
    .applyBatch(
        List.of(
            AddReviewActionRequest.builder()
                .restaurantId("restaurantId1")
                .reviewRating(5)
                .reviewSummary("It was great!")
                .build(),
            AddReviewActionRequest.builder()
                .restaurantId("restaurantId2")
                .reviewRating(4)
                .reviewSummary("Good food but service can improve.")
                .build()
        ),
        ReturnEditsMode.ALL
    );


responseAction.getActionEdits().get().accept(new ActionEditsVisitor<Void>() {
        @Override
        public Void objectEdits(ObjectEdits response) {
            System.out.println("Edited Objects " + response);
            return null;
        }

        @Override
        public Void largeScaleObjectEdits(ObjectTypeEdits response) {
            System.out.println("Edited ObjectTypes: " + response);
            return null;
        }
    });

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 Java SDK, a user can execute Foundry Functions through generated queries.

By adding your functions to your application, you can generate Queries that call FoO to execute logic and get the result.

In this example, we have a function findSimilarRestaurants that takes in an ID and returns an ObjectSet 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 access and execute a query. This is done by accessing .queries() and executing the logic function through .execute(...).getReturnValue()

Example Query:

RestaurantObjectSet response = client
    .ontology()
    .queries()
    .findSimilarRestaurants()
    .execute("restaurantId")
    .getReturnValue();

Media reference properties¶

A media reference in the Palantir platform is a reference to a piece of media present in a MediaSet.

Within the Java SDK, a user can add a media reference property that allows them to upload and download media to the backing media set.

In the following example, we have a restaurantMenu property that represents the menu associated with a particular Restaurant object.

Property for accessing media on `Restaurants`(`restaurantMenu`)¶

Property	API Name	Type
`Restaurant Menu`	`restaurantMenu`	Media

We also have an Action defined as ChangeMenu that allows us to modify the associated restaurantMenu with a Restaurant.

Parameters for changing the menu of a `Restaurant` (`ChangeMenu`)¶

Property	API Name	Type
`Restaurant Id`	`restaurantId`	String
`Restaurant Menu`	`restaurantMenu`	Media

Object/interface with a media reference property¶

Restaurant restaurant = client.ontology().objects().Restaurant().fetch(primaryKey).orElseThrow();
Media restaurantMenu = restaurant.restaurantMenu().get();

Media reference property definition¶

The media reference property is exposed as an interface to the user. The property has functions that fetch data that are implemented internally and not exposed to the user. You can get the underlying MediaReferenceId by accessing getId():

public interface Media {

    /**
     * Get the identifier for the media reference.
     */
    MediaReferenceId getId();

    /**
     * Fetch an object's media reference property metadata.
     */
    MediaMetadata fetchMetadata();

    /**
     * Opens a new stream to load the media
     * file associated with an object's media reference property.
     */
    @MustBeClosed
    InputStream openStream();
}

Fetch metadata¶

To get the MediaMetadata, call restaurantMenu.fetchMetadata():

Media restaurantMenu = restaurant.restaurantMenu().get();
MediaMetadata restaurantMenuMetadata = restaurantMenu.fetchMetadata();

Download media¶

To download media, call restaurantMenu.openStream() to receive a stream to fetch the contents:

try (InputStream inputStream = restaurant.restaurantMenu().get().openStream()) {
        byte[] fileBytes = inputStream.readAllBytes();
    } catch (IOException e) {
        throw new RuntimeException(e);
    }

Upload media¶

To upload a media file, first upload to the backing media set itself. Then, link the uploaded MediaItem to a specific object.

Each ObjectSet will have a method to upload media to a specific property’s backing MediaSet. This returns a Media instance representing the uploaded media's media reference. In this example, the object has a generated uploadRestaurantMenu() method that allows you to upload media to the backing MediaSet:

Media media =
        client.ontology()
                .objects()
                .Restaurant()
                .uploadRestaurantMenu(UploadMediaRequest.builder()
                        .mediaItemPath(...)
                        .mediaType(...)
                        .inputStream(...)
                        .build());

Once successfully uploaded, you can use the returned Media object to link the uploaded media item to a corresponding object by executing the appropriate Action.

Media in actions¶

After uploading and getting a resulting Media object, you can use the media reference on an Action to associate the media reference with a specific object's media property:

client.ontology()
        .actions()
        .changeMenuAction()
        .apply(ChangeMenuActionRequest.builder()
                .restaurant_menu(media)
                .build());

You can also use another object’s media reference in an Action:

client.ontology()
        .actions()
        .changeMenuAction()
        .apply(ChangeMenuActionRequest.builder()
                .restaurant_menu(restaurant.restaurantMenu().get())
                .build());

Note that the media reference must reference the same MediaSet wherever it is used. This means that you cannot upload a MediaItem to MediaSet A and then link that MediaItem to MediaSet B, for example.

中文翻译¶

Java OSDK¶

本文档以示例餐厅对象及其关联的操作（Actions）和查询（Queries）为基础，提供 Java OSDK 的通用文档。您可以使用平台中的开发者控制台（Developer Console）根据您的特定本体生成文档。

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

加载单个 `Restaurant`¶

参数：

primaryKey string：要获取的 Restaurant 的主键示例查询：

Restaurant result = client.ontology().objects().Restaurant().fetch("primaryKey").orElseThrow();

示例 API 响应：

{
    "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
    "__primaryKey": "Restaurant Id",
    "eMail": "E Mail",
    "restaurantId": "Restaurant Id",
    "address": "Address",
    "reviewSummary": "Review Summary",
    "phoneNumber": "Phone Number",
    "numberOfReviews": 123,
    "restaurantName": "Restaurant Name"
}

加载 `Restaurants` 流¶

加载可收集的对象流。该方法会根据用户流式处理的对象数量自动加载对象页面。

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

示例查询：

Stream<Restaurant> result = client.ontology().objects().Restaurant().fetchStream()

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "eMail": "E Mail",
            "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 条；如果请求的 Restaurants 超过 10,000 条，将抛出 ObjectsExceededLimit 错误。

示例查询：

List<Restaurant> result = client.ontology().objects().Restaurant().fetchStream().toList()

示例 API 响应：

{
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "eMail": "E Mail",
            "restaurantId": "Restaurant Id",
            "address": "Address",
            "reviewSummary": "Review Summary",
            "phoneNumber": "Phone Number",
            "numberOfReviews": 123,
            "restaurantName": "Restaurant Name"
        }
        // ... 数据其余部分
    ]
}

加载排序结果¶

通过为特定属性指定排序方向来加载有序的 Restaurants 列表。通过 API 调用时，排序条件通过 fields 数组指定。通过 SDK 调用时，您可以链式调用多个 orderBy。字符串的排序顺序区分大小写，这意味着数字会排在大写字母之前，大写字母会排在小写字母之前。例如，Cat 会排在 bat 之前。

参数：

ordering {ObjectType}Ordering：要排序的属性。使用 Java SDK 时，通过 {ObjectType}Ordering 接口提供。
属性名称和方向 ASC| DESC：排序方向，升序或降序。使用 Java SDK 时，通过 {ObjectType}Ordering 接口上的 {PROPERTY_NAME}_ASC 和 {PROPERTY_NAME}_DESC 限定符提供。

示例查询：

Stream<Restaurant> result = client.ontology()
    .objects()
    .Restaurant()
    .orderBy(RestaurantOrdering.RESTAURANT_NAME_ASC)
    .fetchStream();

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Object A",
            "restaurantName": "A"
            // ...其余属性
        },
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Object B",
            "restaurantName": "B"
            // ...其余属性
        }
        // ...页面其余部分
    ]
}

过滤¶

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

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

参数：

where Filter（可选）：对特定属性进行过滤。可能的操作取决于属性的类型。通过 {ObjectType}Filter 表示，并为每个属性提供可调用的方法。
orderBy OrderBy（可选）：根据特定属性对结果进行排序。如果使用 SDK，可以通过链式调用 .where 和 orderBy 来实现相同的结果。通过 {ObjectType}OrderBy 表示，并为每个属性提供可调用的方法。

示例查询：

List<Restaurant> result = client.ontology()
    .objects()
    .Restaurant()
    .where(RestaurantFilter.restaurantName().isNull(false))
    .fetchStream()
    .toList();

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": null
            // ... 其余属性
        }
        // ... 页面其余部分
    ]
}

搜索过滤器类型 (`RestaurantFilter`)¶

开头匹配 (Starts with)¶

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

参数：

field method：要使用的属性名称（例如，restaurantName）。
value string：用于与 Restaurant Name 进行前缀匹配的值。例如，"foo" 将匹配 "foobar"，但不匹配 "barfoo"。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Restaurant()
    .where(RestaurantFilter.restaurantName().startsWith("foo"));

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": "foobar"
            // ... 其余属性
        }
    ]
}

包含任意词 (Contains any terms)¶

仅适用于字符串属性。返回 restaurantName 包含提供的值中任意空格分隔词（不区分大小写，顺序不限）的 Restaurants。

参数：

field method：要使用的属性名称（例如，restaurantName）。
value string：要匹配的空格分隔词集。例如，"foo bar" 将匹配 "bar baz"，但不匹配 "baz qux"。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().containsAnyTerm("foo bar"));

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": "foo bar baz"
            // ... 其余属性
        },
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000001",
            "restaurantName": "bar baz"
            // ... 其余属性
        }
    ]
}

包含所有词 (Contains all terms)¶

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

参数：

field method：要使用的属性名称（例如，restaurantName）。
value string：要匹配的空格分隔词集。例如，"foo bar" 将匹配 "hello foo baz bar"，但不匹配 "foo qux"。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().containsAllTerms("foo bar"));

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": "hello foo baz bar"
            // ... 其余属性
        }
    ]
}

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

仅适用于字符串属性。返回 restaurantName 按提供的顺序包含所有词（不区分大小写）的 Restaurants，但这些词必须相邻。

参数：

field method：要使用的属性名称（例如，restaurantName）。
value string：要匹配的空格分隔词集。例如，"foo bar" 将匹配 "hello foo bar baz"，但不匹配 "bar foo qux"。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().containsAllTermsInOrder("foo bar"));

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": "foo bar baz"
            // ... 其余属性
        }
    ]
}

范围比较 (Range comparison)¶

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

参数：

field method：要使用的属性名称（例如，restaurantName）。
value string：与 Restaurant Name 进行比较的值

比较类型：

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

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().lt("Restaurant Name"));

等于 (Equal to)¶

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

参数：

field method：要使用的属性名称（例如，restaurantName）。
value string：与 Restaurant Name 进行相等性检查的值。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().eq("Restaurant Name"));

示例 API 响应：

{
    "nextPageToken": "v1.000000000000000000000000000000000000000000000000000000000000000000000000",
    "data": [
        {
            "__rid": "ri.phonograph2-objects.main.object.00000000-0000-0000-0000-000000000000",
            "__primaryKey": "Restaurant Id",
            "restaurantName": "Restaurant Name"
            // ... 其余属性
        }
    ]
}

空值检查 (Null check)¶

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

参数：

field method：要使用的属性名称（例如，restaurantName）。
value boolean：Restaurant Name 是否存在。注意，对于 TypeScript SDK，您需要使用 not 过滤器来检查字段是否非空。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(RestaurantFilter.restaurantName().isNull(true));

`Not` 过滤器¶

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

参数：

value Filter：要反转的搜索查询。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(
        RestaurantFilter.$not(
            RestaurantFilter.restaurantName().isNull(true)
        )
    );

`And` 过滤器¶

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

参数：

value Filter[]：要执行 and 运算的搜索查询集。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(
        RestaurantFilter.$and(
            RestaurantFilter.restaurantName().isNull(false),
            RestaurantFilter.restaurantName().eq("<primarykey>")
        )
    );

`Or` 过滤器¶

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

参数：

value Filter[]：要执行 or 运算的搜索查询集。

示例查询：

RestaurantObjectSet result = client.ontology()
    .objects()
    .Aircraft()
    .where(
        RestaurantFilter.$or(
            RestaurantFilter.restaurantName().isNull(false),
            RestaurantFilter.restaurantName().eq("<primarykey>")
        )
    );

聚合 (Aggregations)¶

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

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

对 Restaurants 执行聚合。

参数：

aggregation Aggregation[]（可选）：要执行的聚合函数集。使用 SDK 时，聚合计算可以通过 .where 与进一步搜索链式调用。
groupBy GroupBy[]（可选）：为聚合结果创建的分组集。
where Filter（可选）：对特定属性进行过滤。可能的操作取决于属性的类型。

示例查询：

AggregationResponse numRestaurants = client.ontology()
        .objects()
        .Restaurants()
        .where(RestaurantFilter.restaurantName().isNull(false))
        .groupBy(GroupBy.exact(Restaurant.Property.restaurantName()))
        .count()
        .compute();

示例 API 响应：

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

聚合类型 (`Aggregation`)¶

近似去重计数 (Approximate distinct)¶

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

参数：

field Property：要使用的属性名称（例如，restaurantName）。
name string（可选）：计算计数的别名。默认为 distinctCount。

示例查询：

Double distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .approximateDistinct(Restaurant.Property.restaurantName())
        .compute();

// 等同于上述查询，但使用 metricName 作为指标名称，而非默认的 "distinctCount"

AggregationResponse distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .aggregate(
            Map.of(
                "metricName",
                Aggregation.approximateDistinct(Restaurant.Property.restaurantName())
            )
        )
        .compute();

示例 API 响应：

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

计数 (Count)¶

计算 Restaurants 的总数。

参数：

name string（可选）：计算计数的别名。默认为 count。

示例查询：

Double distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .count()
        .compute();

示例 API 响应：

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

数值聚合 (Numeric aggregations)¶

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

参数：

field NumericProperty：要使用的属性名称（例如，numberOfReviews）。
name string（可选）：计算值的别名。

聚合类型：

平均值：avg()
最大值：max()
最小值：min()
总和：sum()

示例查询：

Double avgReviewScore = client.ontology()
        .objects()
        .Restaurant()
        .avg(Restaurant.Property.numberOfReviews())
        .compute();

// 等同于上述查询，但使用 avgReview 作为指标名称，而非默认的 "avg"

AggregationResponse distinctRestaurants = client.ontology()
        .objects()
        .Restaurant()
        .aggregate(
            Map.of(
                "avgReview",
                Aggregation.avg(Restaurant.Property.numberOfReviews())
            )
        )
        .compute();

示例 API 响应：

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

分组类型 (`GroupBy`)¶

精确分组 (Exact grouping)¶

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

参数：

field Property：要使用的属性名称（例如，restaurantName）。
maxGroupCount integer（可选）：要创建的 restaurantName 分组的最大数量。

示例查询：

AggregationResponse groupedRestaurants = client.ontology()
       .objects()
       .Restaurant()
       .groupBy(GroupBy.exact(Restaurant.Property.restaurantName()))
       .count()
       .compute();

示例 API 响应：

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

数值分桶 (Numeric bucketing)¶

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

参数：

field NumericProperty：要使用的属性名称（例如，numberOfReviews）。
fixedWidth integer（可选）：将所选属性划分成的每个桶的宽度。

示例查询：

AggregationResponse groupedRestaurants = client.ontology()
       .objects()
       .Restaurant()
       .groupBy(GroupBy.fixedWidth(Restaurant.Property.numberOfReviews(), 10))
       .count()
       .compute();

示例 API 响应：

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

范围分组 (Range grouping)¶

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

参数：

field NumericProperty | DateProperty | TimestampProperty：要使用的属性名称（例如，numberOfReviews）。
ranges AggregationRange[]（可选）：具有包含性起始值和排他性结束值的范围集。

示例查询：

AggregationResponse groupedRestaurants = client.ontology()
    .objects()
    .Restaurant()
    .groupBy(
        GroupBy.range(
            Restaurant.Property.numberOfReviews(),
            List.of(
                AggregationRange.of(0, 3),
                AggregationRange.of(3, 5)
            )
        )
    )
    .count()
    .compute();

示例 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)¶

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

参数：

field DateProperty | TimestampProperty：要使用的属性名称（例如，dateOfOpening）。
value integer（可选）：分组依据的持续时间单位数量。

持续时间类型：

秒 bySeconds()
分钟 byMinutes()
小时 byHours()
天 byDays()
周 byWeeks()
月 byMonths()
季度 byQuarters()
年 byYears()

示例查询：

AggregationResponse groupedRestaurants = client.ontology()
       .objects()
       .Restaurant()
       .groupBy(GroupBy.byDays(Restaurant.Property.dateOfOpening(), 10))
       .count()
       .compute();

示例 API 响应：

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

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

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

为 `Restaurant` 添加评论的参数 (`AddRestaurantReview`)¶

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

应用操作 (Apply action)¶

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

参数：

parameters Object：参数 ID 到这些输入参数值的映射。
restaurantId string
reviewRating integer
reviewSummary string
options integer（可选）：分组依据的持续时间单位数量。

示例查询：

AddReviewActionResponse response = client.ontology()
    .actions()
    .addReview()
    .apply(
        AddReviewActionRequest.builder()
            .restaurantId(restaurantId)
            .reviewRating(5)
            .reviewSummary("It was great!")
            .build(),
        ReturnEditsMode.ALL
    );

response.getValidationResult().accept(new ActionValidationVisitor<Object>() {
    @Override
    public Object valid(ActionValidationResponse response) {
        System.out.println("Review added successfully " + response);
        return null;
    }

    @Override
    public Object invalid(ActionValidationResponse response) {
        System.out.println("Review validation failed! " + response);
        return null;
    }
});

示例 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 Object：参数 ID 到这些输入参数值的映射。
restaurantId string
reviewRating integer
reviewSummary string
value ReturnEditsMode.(ALL|NONE)（可选）：应用操作后是否在响应中返回编辑结果。

示例查询：

AddReviewBatchActionResponse response = client.ontology()
    .actions()
    .addReview()
    .applyBatch(
        List.of(
            AddReviewActionRequest.builder()
                .restaurantId("restaurantId1")
                .reviewRating(5)
                .reviewSummary("It was great!")
                .build(),
            AddReviewActionRequest.builder()
                .restaurantId("restaurantId2")
                .reviewRating(4)
                .reviewSummary("Good food but service can improve.")
                .build()
        ),
        ReturnEditsMode.ALL
    );


responseAction.getActionEdits().get().accept(new ActionEditsVisitor<Void>() {
        @Override
        public Void objectEdits(ObjectEdits response) {
            System.out.println("Edited Objects " + response);
            return null;
        }

        @Override
        public Void largeScaleObjectEdits(ObjectTypeEdits response) {
            System.out.println("Edited ObjectTypes: " + response);
            return null;
        }
    });

示例响应：

{
    "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）是一项强大的功能，旨在增强数据建模和操作。函数提供了一种定义和执行本体中存储数据的自定义逻辑的方法，允许用户创建更复杂的数据转换、验证和分析。

在 Java SDK 中，用户可以通过生成的查询来执行 Foundry 函数。

通过将函数添加到应用程序中，您可以生成调用 FoO 来执行逻辑并获取结果的查询。

在此示例中，我们有一个函数 findSimilarRestaurants，它接受一个 ID 并返回包含所有相似 Restaurants 的 ObjectSet。

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

属性	API 名称	类型
`Restaurant Id`	`restaurantId`	String

返回：RestaurantObjectSet

应用函数 (Apply function)¶

要应用函数，您必须访问并执行一个查询。这是通过访问 .queries() 并通过 .execute(...).getReturnValue() 执行逻辑函数来完成的。

示例查询：

RestaurantObjectSet response = client
    .ontology()
    .queries()
    .findSimilarRestaurants()
    .execute("restaurantId")
    .getReturnValue();

媒体引用属性 (Media reference properties)¶

Palantir 平台中的媒体引用是对 MediaSet 中存在的媒体文件的引用。

在 Java SDK 中，用户可以添加一个媒体引用属性，允许他们向底层媒体集 upload 和 download 媒体。

在以下示例中，我们有一个 restaurantMenu 属性，表示与特定 Restaurant 对象关联的菜单。

访问 `Restaurants` 上媒体的属性 (`restaurantMenu`)¶

属性	API 名称	类型
`Restaurant Menu`	`restaurantMenu`	Media

我们还定义了一个名为 ChangeMenu 的操作，允许我们修改与 Restaurant 关联的 restaurantMenu。

更改 `Restaurant` 菜单的参数 (`ChangeMenu`)¶

属性	API 名称	类型
`Restaurant Id`	`restaurantId`	String
`Restaurant Menu`	`restaurantMenu`	Media

具有媒体引用属性的对象/接口¶

Restaurant restaurant = client.ontology().objects().Restaurant().fetch(primaryKey).orElseThrow();
Media restaurantMenu = restaurant.restaurantMenu().get();

媒体引用属性定义¶

媒体引用属性作为接口暴露给用户。该属性具有获取数据的函数，这些函数在内部实现，不暴露给用户。您可以通过访问 getId() 获取底层的 MediaReferenceId：

public interface Media {

    /**
     * 获取媒体引用的标识符。
     */
    MediaReferenceId getId();

    /**
     * 获取对象的媒体引用属性元数据。
     */
    MediaMetadata fetchMetadata();

    /**
     * 打开一个新的流来加载与对象的媒体引用属性关联的媒体文件。
     */
    @MustBeClosed
    InputStream openStream();
}

获取元数据 (Fetch metadata)¶

要获取 MediaMetadata，请调用 restaurantMenu.fetchMetadata()：

Media restaurantMenu = restaurant.restaurantMenu().get();
MediaMetadata restaurantMenuMetadata = restaurantMenu.fetchMetadata();

下载媒体 (Download media)¶

要下载媒体，请调用 restaurantMenu.openStream() 以接收一个流来获取内容：

try (InputStream inputStream = restaurant.restaurantMenu().get().openStream()) {
        byte[] fileBytes = inputStream.readAllBytes();
    } catch (IOException e) {
        throw new RuntimeException(e);
    }

上传媒体 (Upload media)¶

要上传媒体文件，首先上传到底层媒体集本身。然后，将上传的 MediaItem 链接到特定对象。

每个 ObjectSet 都会有一个方法，用于将媒体上传到特定属性的底层 MediaSet。这将返回一个 Media 实例，表示上传媒体的媒体引用。在此示例中，对象有一个生成的 uploadRestaurantMenu() 方法，允许您将媒体上传到底层 MediaSet：

Media media =
        client.ontology()
                .objects()
                .Restaurant()
                .uploadRestaurantMenu(UploadMediaRequest.builder()
                        .mediaItemPath(...)
                        .mediaType(...)
                        .inputStream(...)
                        .build());

成功上传后，您可以使用返回的 Media 对象，通过执行相应的操作将上传的媒体项链接到对应的对象。

操作中的媒体 (Media in actions)¶

上传并获取结果 Media 对象后，您可以在操作上使用媒体引用，将媒体引用与特定对象的媒体属性关联：

```java client.ontology() .actions() .changeMenuAction() .apply(ChangeMenuAction

Java OSDK¶

Load single Restaurant¶

Load a stream of Restaurants¶

Load all Restaurants¶

Load ordered results¶

Filtering¶

Types of search filters (RestaurantFilter)¶

Starts with¶

Contains any terms¶

Contains all terms¶

Contains all terms in order¶

Range comparison¶

Equal to¶

Null check¶

Not filter¶

And filter¶

Or filter¶

Aggregations¶

Types of aggregations (Aggregation)¶

Approximate distinct¶

Count¶

Numeric aggregations¶

Types of group bys (GroupBy)¶

Exact grouping¶

Numeric bucketing¶

Range grouping¶

Datetime grouping¶

Actions on the Ontology¶

Parameters for adding a review to a Restaurant (AddRestaurantReview)¶

Apply action¶

Apply batch action¶

Functions¶

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

Apply function¶

Media reference properties¶

Property for accessing media on Restaurants(restaurantMenu)¶

Parameters for changing the menu of a Restaurant (ChangeMenu)¶

Object/interface with a media reference property¶

Media reference property definition¶

Fetch metadata¶

Download media¶

Upload media¶

Media in actions¶

中文翻译¶

Java OSDK¶

加载单个 Restaurant¶

加载 Restaurants 流¶

加载所有 Restaurants¶

加载排序结果¶

过滤¶

搜索过滤器类型 (RestaurantFilter)¶

开头匹配 (Starts with)¶

包含任意词 (Contains any terms)¶

包含所有词 (Contains all terms)¶

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

范围比较 (Range comparison)¶

等于 (Equal to)¶

空值检查 (Null check)¶

Not 过滤器¶

And 过滤器¶

Or 过滤器¶

聚合 (Aggregations)¶

聚合类型 (Aggregation)¶

近似去重计数 (Approximate distinct)¶

计数 (Count)¶

数值聚合 (Numeric aggregations)¶

分组类型 (GroupBy)¶

精确分组 (Exact grouping)¶

数值分桶 (Numeric bucketing)¶

范围分组 (Range grouping)¶

日期时间分组 (Datetime grouping)¶

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

为 Restaurant 添加评论的参数 (AddRestaurantReview)¶

应用操作 (Apply action)¶

应用批量操作 (Apply batch action)¶

函数 (Functions)¶

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

应用函数 (Apply function)¶

媒体引用属性 (Media reference properties)¶

访问 Restaurants 上媒体的属性 (restaurantMenu)¶

Load single `Restaurant`¶

Load a stream of `Restaurants`¶

Load all `Restaurants`¶

Types of search filters (`RestaurantFilter`)¶

`Not` filter¶

`And` filter¶

`Or` filter¶

Types of aggregations (`Aggregation`)¶

Types of group bys (`GroupBy`)¶

Parameters for adding a review to a `Restaurant` (`AddRestaurantReview`)¶

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

Property for accessing media on `Restaurants`(`restaurantMenu`)¶

Parameters for changing the menu of a `Restaurant` (`ChangeMenu`)¶

加载单个 `Restaurant`¶

加载 `Restaurants` 流¶

加载所有 `Restaurants`¶

搜索过滤器类型 (`RestaurantFilter`)¶

`Not` 过滤器¶

`And` 过滤器¶

`Or` 过滤器¶

聚合类型 (`Aggregation`)¶

分组类型 (`GroupBy`)¶

为 `Restaurant` 添加评论的参数 (`AddRestaurantReview`)¶

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

访问 `Restaurants` 上媒体的属性 (`restaurantMenu`)¶

更改 `Restaurant` 菜单的参数 (`ChangeMenu`)¶