Skip to main content
Version: v5.0

How to set up a Related Query tool

Overview#

This page describes an example of how to set up a Related Query tool which is used to generate Item Service related queries such as:

  • $findInCollections
  • $findWithRelated
  • $findWithRelatedGraph

Example use case#

The following example demonstrates the usage of the Related Query Tool based on the requirement to retrieve platform data using natural language inputs. In this example, we want to be able to query a fire protection system and a HVAC system and easily retrieve sensor data for pressure and temperature readings.

Assume the namespace contains the following collections, each with related item types:

  • System Collection – contains system-related items.
  • System Components Collection – contains items such as FireProtectionSystemComponent and HVACSystemComponent.
  • System Sensor Points Collection – contains SensorDataPoint items, which generate PressureReading and TemperatureReading data.

Steps for setting up a Related Query tool#

To set up a Related Query tool, do the following:

  1. Configure schema definitions in the Item Service.
  2. Create an agent using IafAISvc.createAgents.
  3. Create a team using IafAISvc.createTeam.
  4. Initiate conversation with the team using IafAISvc.createConversation.
  5. Continue the conversation with IafAISvc.createConversation.

Step 1: Configure schema definitions in the Item Service#

The first step is to set up schema definitions which are mandatory for using the Related Query tool. Refer to the section Configure Schema Definitions for more information.

The example queries on this page are based on this reference schema definition.

Step 2: Create an agent using IafAISvc.createAgents#

To create an agent do the following:

[    {        "_name": "AC - Related Query Helper Agent",        "_background": "It interacts with Related Query Tool to generate related queries as JSON based on user prompt ",        "_userType": "related_query_helper_agent",        "_namespaces": [            "Amoghtestworkspace_m8NrvPU3"        ],        "_config": {            "_model": "gpt-4o",            "_provider": "openai"        },        "_tools": [            "RelatedQueryTool"        ]    }]

Note: You can use RelatedQueryTool together with the SearchRelatedItemsTool system tool to retrieve item-service results for the query generated by RelatedQueryTool

Step 3: Create a team using IafAISvc.createTeam#

To create a team, do the following:

  1. Create a team with the agent you created using IafAISvc.createTeam.
  2. Use the agent’s _userType to reference the specific agent to include. Refer to the code example below for more information.
{    "_name": "The Related Query Team",    "_namespaces": ["Amoghtestworkspace_m8NrvPU3"],    "_agents": [       {"_userType": "related_query_helper_agent"}    ],    "_flow": [        {"from": "__start__", "to": "related_query_helper_agent"},        {"from": "related_query_helper_agent", "to": "__end__"}    ]}

Step 4: Initiate conversation with the team using IafAISvc.createConversation#

Do the following:

  1. Start the conversation using the team’s _id from the previous request.
  2. Pass your prompt in the _input.message field. Refer to the sample prompt below.

Sample Prompt:

{    "_input": {      "message": "Generate Item service realted query to get systems and its system collection"    },    "_namespaces": ["Amoghtestworkspace_m8NrvPU3"],    "_teamId": "f24eea61-be27-493e-9a04-f5afc80acef6"}

Sample Response:

{  "$findWithRelated": {    "parent": {      "collectionDesc": {        "_userType": "system_collection",        "_itemClass": "NamedUserCollection",        "_versions.all": false      },      "query": {},      "options": {        "project": {},        "page": {          "_pageSize": 100,          "_offset": 0        },        "sort": {}      }    },    "related": [      {        "relatedDesc": {          "_relatedUserType": "system_component_collection",          "_relatedUserItemClass": "NamedUserCollection",          "_isInverse": false        },        "query": {},        "options": {          "project": {},          "page": {            "_pageSize": 100,            "_offset": 0          },          "sort": {}        },        "as": "systemComponents"      }    ]  }}

Step 5: Continue the conversation with IafAISvc.createConversation#

Do the following:

  1. Continue the conversation by including the conversation’s _id from the previous response.
  2. Include this _id in upcoming requests to maintain context. See example below.
{    "_input": {        "message": "another prompt here..."    },    "_namespaces": ["Amoghtestworkspace_m8NrvPU3"],    "_teamId": "f24eea61-be27-493e-9a04-f5afc80acef6",    "_id": "fc4fb00e-ce9f-44df-8b3d-777a5bd0737b"}

Note: If you omit the _id, a new conversation will be started instead of continuing the existing one.

Configure schema definitions#

Schema definitions are mandatory for using the RelatedQueryTool and GraphQueryTool.

You can create schema definitions along with a NamedUserCollection. Alternatively, you can create the schema definitions and update the types in Named User, File or Telemetry Collections.

This results in two distinctive approves to defining schemas:

See section below for detailed steps.

Option 1: Assume you have the collections already#

For this approach, do the following:

  1. Generate SchemaDefinitions using IafItemSvc.generateSchemaDefinitions
  2. Modify the schema definitions
  3. Update SchemaDefinitions using IafItemSvc.updateSchemaDefinitions
  4. Update NamedUserCollection using IafItemSvc.updateNamedUserItem

Generate SchemaDefinitions using IafItemSvc.generateSchemaDefinitions#

Use IafItemSvc.generateSchemaDefinitions to generate sample schema definitions based on an existing RelatedItem. This utility retrieves all NamedUserCollection entries, selects the first RelatedItem, and its first Reading (for ReadingTypes), to construct an initial schema.

Note: this does not create a schema definition in the system. It simply serves as a helper to reduce the effort of creating a SchemaDefinition from scratch. After creating the schema, you can modify the schema as needed and use updateSchemaDefinitions to apply the changes. Ensure that the corresponding item types in each NamedUserCollection are also updated accordingly.

Modify the schema definitions#

Manually edit the schema retrieved from the previous step to suit your requirements.

Update SchemaDefinitions using IafItemSvc.updateSchemaDefinitions#

Use IafItemSvc.updateSchemaDefinitions to make the required updates on the schema definitions.

Update NamedUserCollection using IafItemSvc.updateNamedUserItem#

Update each NamedUserCollection with its item type. Refer to the example code below.

{    "_uri": "/nameduseritems/686cfd1216754c72cd16a989",    "_name": "Space Collection",    "_userType": "iaf_ext_space_coll",    "_tipId": "686cfd1216754c72cd16a98a",    "_irn": "itemsvc:nameduseritem:686cfd1216754c72cd16a989",    "_itemTypes": [        "PhysicalSpace"    ],    "_description": "Physical Space Collection"}

Option 2: Create collections along with schema definitions#

This approach involves just one step, create named user collection along with schema definitions. See example code listing below. 

[    {        "_name": "Building assets Collection",        "_userType": "iaf_ext_asset_coll1",        "_itemClass": "NamedUserCollection",        "_namespaces": [            {{nsfilter}}        ],        "_shortName": "test_Coll",        "_schemaDefinitions": {            "_itemTypes": [                {                    "_typeName": "Asset",                    "_description": "It hold all the Asset objects inthe project",                    "_properties": {                        "Building": {                            "_type": "string",                            "_description": "It holds information about the building"                        },                        "Floor": {                            "_type": "string",                            "_description": "It holds details about the floor"                        },                        "Revision": {                            "_type": "string"                        }                    }                }            ]        }    }]