Skip to main content
Version: Next

$entityset

Functionality​

Definition​

The $entityset endpoint enables you to manage and manipulate entity sets in your data collection. After creating an entity set using the $method=entityset parameter, you can perform various operations on these entity sets to retrieve, compare, and combine them as needed.

Syntaxes​

SyntaxExampleDescription
$entityset/{entitySetID}/People/$entityset/0ANUMBERRetrieves an existing entity set
$entityset/{entitySetID}?$operator...&$otherCollection/Employee/$entityset/0ANUMBER?$logicOperator=AND&$otherCollection=C0ANUMBERCreates a new entity set by comparing existing entity sets

Combining with Other Parameters​

The $entityset parameter can be combined with other parameters to enhance functionality:

  • $filter: Define a filter to create an entity set based on specific criteria.

  • $orderby: Specify the order in which entities are sorted in the entity set.

  • $top/$limit and $skip: Limit the number of entities in the entity set and skip a certain number of entities.

  • $expand: Include related data within the entity set.

  • $attributes: Specify which attributes to include in the entity set.

  • $timeout: Define the duration for which the entity set will be saved in the server's cache.

  • $savedfilter: Save the filter criteria used when creating the entity set for future retrieval.

  • $savedorderby: Save the sort order used when creating the entity set for future retrieval.

Use Cases​

Retrieving an Existing Entity Set​

You can retrieve an existing entity set by its ID. This allows you to execute operations on a previously defined entity set. Entity sets have a time limit, either by default or as specified using the $timeout parameter. You can also save filter and order by statements with $savedfilter and $savedorderby when creating an entity set.

Syntax​

GET /rest/{{dataClass}}/$entityset/{{entitySetID}}
info
  • entitySetID: The unique ID of the entity set.

Operations​

When you retrieve an existing entity set, you can apply any of the following operations to it:

  • $expand: Expand related entities.
  • $filter: Apply filter criteria.
  • $orderby: Order the results.
  • $skip: Skip a specified number of entities.
  • $top/$limit: Limit the number of entities returned.

Example​

After creating an entity set, you retrieve it as follows:

GET /rest/Employee/$entityset/9718A30BF61343C796345F3BE5B01CE7

Creating a New Entity Set from Existing Ones​

You can create a new entity set by comparing two existing entity sets using logical operators. The logical operators define the relationship between the two sets, such as intersection, union, and difference.

Syntax​

GET /rest/{{dataClass}}/$entityset/{{entitySetID}}?$logicOperator={{operator}}&$otherCollection={{otherEntitySetID}}&$method=entityset
info
  • entitySetID: The unique ID of the first entity set.
  • $logicOperator: The logical operator to apply (AND, OR, EXCEPT, INTERSECT).
  • $otherCollection: The unique ID of the second entity set.

Logical Operators​

OperatorDescription
ANDReturns the entities common to both entity sets
ORReturns the entities in either entity set
EXCEPTReturns the entities in the first entity set minus those in the second
INTERSECTReturns true if there is an intersection, otherwise false
info

Logical operators are not case-sensitive (e.g., "AND" or "and").

Example​

Using AND to Return Common Entities

GET /rest/Employee/$entityset/9718A30BF61343C796345F3BE5B01CE7?$logicOperator=AND&$otherCollection=C05A0D887C664D4DA1B38366DD21629B

Using INTERSECT to Check for Intersection

GET /rest/Employee/$entityset/9718A30BF61343C796345F3BE5B01CE7?$logicOperator=INTERSECT&$otherCollection=C05A0D887C664D4DA1B38366DD21629B
info

If there is an intersection, this query returns true. Otherwise, it returns false.

Using OR to Combine Entity Sets

GET /rest/Employee/$entityset/9718A30BF61343C796345F3BE5B01CE7?$logicOperator=OR&$otherCollection=C05A0D887C664D4DA1B38366DD21629B&$method=entityset

This query creates a new entity set that combines all the entities from both entity sets.

Best Practices​

  • Manage Time Limits: Be aware of the time limits on entity sets and use $timeout to specify your limits if needed.

  • Save Filters and Orderings: Use $savedfilter and $savedorderby to save filter and order by statements for future use.

  • Efficient Comparisons: Use logical operators to efficiently compare and combine entity sets.