Traversed Properties

A search-only construct for advanced search use cases

Traversed Properties play a crucial role in expanding the scope of search functionalities across relationships. Understanding this concept is essential for leveraging the full potential of our platform's search capabilities.

Recipient and Adjacent Resources

Traversed Properties enable users to search across the properties of adjacent resources linked to a recipient resource through relationships. In simpler terms, they allow you to extend your search beyond the immediate properties of a single resource to include properties of related resources.

Before diving deeper, let's clarify a couple of key terms:

• Recipient Resource: This is the focal point of your search. It's the resource against which the search context exists. For example, if you're searching for information about a particular customer, that customer record would be the recipient resource.
• Adjacent Resources and Relationships: These are the relationships and the target resources linked to the recipient resource. In our platform, relationships establish connections between different resources. Adjacent resources are essentially those linked to the recipient resource through adjacent relationships.

Configuring Traversed Properties

Traversed Properties are configured within the context of the recipient resource collection on the data partition. This configuration determines which properties, including those of adjacent resources and relationship instances, are included in the search scope. By effectively configuring Traversed Properties, users can streamline their search processes and uncover interconnected data insights more efficiently.

Traversed Property Notation

Starting from a recipient resource, Traversed Properties from an adjacent relationship or resource can be configured and queried using a special notation:

• @{includeKey}.{propertyKey} (e.g. @locatedAt.startDate).
  This allows to query on the property startDate of the relationship location.
• @{includeKey}.@{resourcetype}.{propertyKey} (e.g. @[email protected]).
  This allows to query on the property address of the resource office that is related to the resource through the location relationship.
• @{includeKey}.@{resourcetype}.{containedKey}.{propertyKey} (e.g. @[email protected]).
  This allows to query on the property address of the contained resource location of the resource office that is related to the resource through the location

Traversed Properties support only primitive and general-purpose complex Clinia Datatypes, but the nested properties of a custom datatype can be queried using the dot notation.

Here's what a Data Partition configuration leveraging traversed properties looks like:

{
  "key": "<partitionKey>",
  "modules": {
    "search": "STANDARD"
  },
  "source": {
    "type": "DATA_SOURCE",
    "key": "<dataSourceKey>",
    "collections": [
      {
        "key": "provider",
        "traversedProperties": [
          "@[email protected]"
        ]
      },
      {
        "key": "office"
      }	
    ],
    "relationships": ["location"]
  }
}

📘

Search-only construct

It is important to note that Traversed Properties are search-only construct. This means that the configured properties will not be added to the recipient resource itself. They are indexed alongside the recipient resource for search purposes, but Traversed Properties will not be returned in the response of a "get by id" HTTP call.

You can still get that information when retrieving a recipient resource by including the adjacent relationships and resources.

🦉

Configure Traversed Properties

Open Recipe

Using Traversed Properties

Querying

When performing a search, you're typically querying properties of the recipient resource. However, with Traversed Properties, you can expand your search to include properties of adjacent resources as well. This means that you're not limited to the immediate properties of the recipient resource; instead, you can traverse through relationships to access and search across properties of linked resources.

Querying for Traversed Properties is no different than querying for regular properties. You just have to use the special notation associated with these type of properties. Refer to the Traversed Property Notation section for more detail.

Real-time update

One of the remarkable features of Traversed Properties is their real-time update mechanism. As properties of adjacent resources and relationships are modified, Traversed Properties are automatically updated to reflect these changes. This ensures that search results remain current and accurate, providing users with the most up-to-date information available.

Example

Let's consider a scenario reusing the typical configuration where we have two types of resources: Offices and Providers.

• Office Resource: Represents a physical place of work and contains properties such as Address to specify the office's location.
• Provider Resource: Represents a healthcare professional linked to one or many offices through an Location relationship.
• Location Relationship: Establishes a connection between Provider and Office resources.

Search Use Case

Let's say we want to support a search use case where users can search for providers working in a specific city. In this scenario, the relevant address information is contained in the adjacent resource Office to the recipient resource Provider.

1. User Query: Search for providers working in New York City.
2. Search Process:
   • The search begins with the recipient resource, which is the Provider.
   • Traversed Properties have been configured to include the Address property of the adjacent Office resource in the Provider recipient resources.
   • The search query is performed on the Provider's Address Traversed Property.
   • The system retrieves Provider who are linked to Offices with addresses in New York City.
3. Search Results:
   • The search results display Providers located at Offices in New York City.
     Users can view detailed information about these Providers, including their specialties, contact information, and Traversed Address properties.

Outcome

In this scenario, Traversed Properties allow users to search for Providers based on the city where they work, even though the address information is contained in the adjacent Office resource. By leveraging relationships and configuring Traversed Properties effectively, our platform enables users to efficiently find healthcare professionals based on their work locations.