IndyKite Developer Hub logo
Back to all resources
ContX IQContX IQJson

ContX IQ: Aggregate Data Using WHERE, WITH, and COUNT Operators

Demonstrates advanced Cypher query patterns including WHERE filtering, WITH for intermediate results, and COUNT for aggregation. Returns Person data with contract counts.

ContX IQ: Aggregate Data Using WHERE, WITH, and COUNT Operators

This example demonstrates aggregation and filtering in ContX IQ queries:

Cypher operators demonstrated:

1. WHERE - produced by the policy filter (numContracts > 1) on the aggregated value

2. WITH - Pass results between query parts (intermediate projection)

3. COUNT - Aggregate and count related nodes

Policy cypher:

MATCH (subject:Person)-[r1:ACCEPTED]->(contract:Contract)

WITH subject, COUNT(contract) AS numContracts

Policy filter: subject.external_id = $subjectId AND numContracts > 1

Allowed reads: subject.*, aggregate_values numContracts

Use cases:

- Dashboard summaries (count related entities)

- Filtered aggregations (count only matching items)

- Multi-step queries with intermediate results

Use case

Scenario: Return a Person together with how many Contracts they accepted, but only when they accepted more than one.

Graph structure:

Person(alice) -[ACCEPTED]-> Contract(ct123)

Person(alice) -[ACCEPTED]-> Contract(ct234)

Person(alice) -[ACCEPTED]-> Contract(ct985)

Person(ryan) and Person(tilda) exist but accepted no contract in this dataset

Query flow:

1. User authenticates with access token (Person subject)

2. Execute with input_params subjectId = alice

3. The policy cypher matches the subject's contracts and aggregates COUNT(contract) AS numContracts with WITH

4. The policy filter keeps the row only if numContracts > 1

5. The query returns subject.external_id and the aggregate value numContracts

6. Returns: [{subject.external_id: "alice", numContracts: 3}]

Key concepts:

- WITH acts as a "checkpoint" in the query, projecting results forward

- COUNT aggregates across relationships

- Filtering happens before or after WITH as needed

ikg

Requirements

Prerequisites:

- ServiceAccount credentials: For creating policies and queries (Bearer token)

- AppAgent credentials: For data ingestion and query execution (X-IK-ClientKey)

- User access token: JWT for the authenticated user

Required API access:

- POST /capture/v1/nodes/ and /capture/v1/relationships/ (data ingestion)

- POST /configs/v1/authorization-policies (create policy)

- POST /configs/v1/knowledge-queries (create query)

- POST /contx-iq/v1/execute (run query)

Steps

Step 1: Ingest Graph Data

- Authentication: AppAgent credential (X-IK-ClientKey header)

- Action: POST the contracts dataset (Person, PaymentMethod, Contract, Vehicle, LicenseNumber, Company, Application nodes); alice accepts ct123, ct234 and ct985

- Result: Graph with a person who accepted several contracts

Step 2: Create Aggregation Policy

- Authentication: ServiceAccount credential (Bearer token)

- Action: POST policy with subject type Person and cypher MATCH (subject:Person)-[r1:ACCEPTED]->(contract:Contract) WITH subject, COUNT(contract) AS numContracts, filter subject.external_id = $subjectId AND numContracts > 1, allowing:

- READ on subject.*

- aggregate_values numContracts

- Result: Policy ID returned

Step 3: Create Aggregation Query

- Authentication: ServiceAccount credential (Bearer token)

- Action: POST query with nodes ["subject.external_id"] and aggregate_values ["numContracts"]

- Result: Query ID returned

Step 4: Execute Aggregation Query

- Authentication: AppAgent credential + User token (Bearer header)

- Action: POST to /contx-iq/v1/execute with input_params subjectId = alice

- Result: one row with subject.external_id alice and aggregate_values numContracts = 3

Step 1

Capture the nodes needed for this use case.

POST https://eu.api.indykite.com/capture/v1/nodes/Json
{
  "nodes": [
    {
      "external_id": "alice",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "alice@email.com"
        },
        {
          "type": "given_name",
          "value": "Alice"
        },
        {
          "type": "last_name",
          "value": "Smith"
        }
      ]
    },
    {
      "external_id": "ryan",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "ryan@yahoo.co.uk"
        },
        {
          "type": "given_name",
          "value": "ryan"
        },
        {
          "type": "last_name",
          "value": "mushu"
        }
      ]
    },
    {
      "external_id": "tilda",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "tilda@yahoo.co.uk"
        },
        {
          "type": "given_name",
          "value": "tilda"
        },
        {
          "type": "last_name",
          "value": "mushu"
        }
      ]
    },
    {
      "external_id": "cb123",
      "type": "PaymentMethod",
      "properties": [
        {
          "type": "payment_name",
          "value": "Credit Card"
        }
      ]
    },
    {
      "external_id": "kl123",
      "type": "PaymentMethod",
      "properties": [
        {
          "type": "payment_name",
          "value": "Klarna"
        }
      ]
    },
    {
      "external_id": "ct123",
      "type": "Contract",
      "properties": [
        {
          "type": "category",
          "value": "Insurance"
        },
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "hfgrten123",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "ct234",
      "type": "Contract",
      "properties": [
        {
          "type": "category",
          "value": "Insurance"
        },
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "hfgrten234",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "ct985",
      "type": "Contract",
      "properties": [
        {
          "type": "category",
          "value": "Insurance"
        },
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "hfgrten985",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "car1",
      "type": "Vehicle",
      "properties": [
        {
          "type": "category",
          "value": "Car"
        },
        {
          "type": "is_active",
          "value": true
        },
        {
          "type": "vin",
          "value": "rtfhcnvjt471"
        }
      ]
    },
    {
      "external_id": "car2",
      "type": "Vehicle",
      "properties": [
        {
          "type": "category",
          "value": "Car"
        },
        {
          "type": "is_active",
          "value": true
        },
        {
          "type": "vin",
          "value": "kdcbfrt178"
        }
      ]
    },
    {
      "external_id": "truck1",
      "type": "Vehicle",
      "properties": [
        {
          "type": "category",
          "value": "Truck"
        },
        {
          "type": "is_active",
          "value": true
        },
        {
          "type": "vin",
          "value": "sncnrkcldp"
        }
      ]
    },
    {
      "external_id": "license1",
      "type": "LicenseNumber",
      "properties": [
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "AX123456",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "license2",
      "type": "LicenseNumber",
      "properties": [
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "OL123456",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "license3",
      "type": "LicenseNumber",
      "properties": [
        {
          "type": "status",
          "value": "Active"
        },
        {
          "type": "number",
          "value": "VN123456",
          "metadata": {
            "assurance_level": 3,
            "source": "BRREG"
          }
        }
      ]
    },
    {
      "external_id": "company1",
      "type": "Company",
      "properties": [
        {
          "type": "name",
          "value": "Company1"
        },
        {
          "type": "registration",
          "value": "256314523"
        }
      ]
    },
    {
      "external_id": "company2",
      "type": "Company",
      "properties": [
        {
          "type": "name",
          "value": "Company2"
        },
        {
          "type": "registration",
          "value": "942365123"
        }
      ]
    },
    {
      "external_id": "application1",
      "type": "Application",
      "properties": [
        {
          "type": "name",
          "value": "Application"
        }
      ]
    },
    {
      "external_id": "application2",
      "type": "Application",
      "properties": [
        {
          "type": "name",
          "value": "Application2"
        }
      ]
    }
  ]
}

Capture the relationships needed for this use case.

POST https://eu.api.indykite.com/capture/v1/relationships/Json
{
  "relationships": [
    {
      "source": {
        "external_id": "ryan",
        "type": "Person"
      },
      "target": {
        "external_id": "cb123",
        "type": "PaymentMethod"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "tilda",
        "type": "Person"
      },
      "target": {
        "external_id": "kl123",
        "type": "PaymentMethod"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "alice",
        "type": "Person"
      },
      "target": {
        "external_id": "cb123",
        "type": "PaymentMethod"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "alice",
        "type": "Person"
      },
      "target": {
        "external_id": "ct123",
        "type": "Contract"
      },
      "type": "ACCEPTED"
    },
    {
      "source": {
        "external_id": "alice",
        "type": "Person"
      },
      "target": {
        "external_id": "ct234",
        "type": "Contract"
      },
      "type": "ACCEPTED"
    },
    {
      "source": {
        "external_id": "alice",
        "type": "Person"
      },
      "target": {
        "external_id": "ct985",
        "type": "Contract"
      },
      "type": "ACCEPTED"
    },
    {
      "source": {
        "external_id": "ct123",
        "type": "Contract"
      },
      "target": {
        "external_id": "car1",
        "type": "Vehicle"
      },
      "type": "COVERS"
    },
    {
      "source": {
        "external_id": "ct985",
        "type": "Contract"
      },
      "target": {
        "external_id": "car1",
        "type": "Vehicle"
      },
      "type": "COVERS"
    },
    {
      "source": {
        "external_id": "ct234",
        "type": "Contract"
      },
      "target": {
        "external_id": "truck1",
        "type": "Vehicle"
      },
      "type": "COVERS"
    },
    {
      "source": {
        "external_id": "car1",
        "type": "Vehicle"
      },
      "target": {
        "external_id": "license1",
        "type": "LicenseNumber"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "truck1",
        "type": "Vehicle"
      },
      "target": {
        "external_id": "license2",
        "type": "LicenseNumber"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "car2",
        "type": "Vehicle"
      },
      "target": {
        "external_id": "license3",
        "type": "LicenseNumber"
      },
      "type": "HAS"
    },
    {
      "source": {
        "external_id": "company1",
        "type": "Company"
      },
      "target": {
        "external_id": "car1",
        "type": "Vehicle"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "company1",
        "type": "Company"
      },
      "target": {
        "external_id": "car2",
        "type": "Vehicle"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "company1",
        "type": "Company"
      },
      "target": {
        "external_id": "truck1",
        "type": "Vehicle"
      },
      "type": "OWNS"
    },
    {
      "source": {
        "external_id": "application1",
        "type": "Application"
      },
      "target": {
        "external_id": "company1",
        "type": "Company"
      },
      "type": "HAS_AGREEMENT_WITH"
    },
    {
      "source": {
        "external_id": "application2",
        "type": "Application"
      },
      "target": {
        "external_id": "company1",
        "type": "Company"
      },
      "type": "HAS_AGREEMENT_WITH"
    }
  ]
}

Step 2

Create a CIQ Policy which designates the Subject node, the cypher, and the nodes allowed to be read.

policy.jsonJson
{
  "meta": {
    "policy_version": "1.0-ciq"
  },
  "subject": {
    "type": "Person"
  },
  "condition": {
    "cypher": "MATCH (subject:Person)-[r1:ACCEPTED]->(contract:Contract) WITH subject, COUNT(contract) AS numContracts",
    "filter": [
      {
        "app": "app1",
        "operator": "AND",
        "operands": [
          {
            "attribute": "subject.external_id",
            "operator": "=",
            "value": "$subjectId"
          },
          {
            "attribute": "numContracts",
            "operator": ">",
            "value": 1
          }
        ]
      }
    ]
  },
  "allowed_reads": {
    "nodes": [
      "subject.*"
    ],
    "aggregate_values": [
      "numContracts"
    ]
  }
}

Request to create the CIQ Policy configuration using REST.

POST https://eu.api.indykite.com/configs/v1/authorization-policiesJson
{
  "project_id": "your_project_gid",
  "description": "description of policy",
  "display_name": "policy name",
  "name": "policy-name",
  "policy": "{\"meta\":{\"policy_version\":\"1.0-ciq\"},\"subject\":{\"type\":\"Person\"},\"condition\":{\"cypher\":\"MATCH (subject:Person)-[r1:ACCEPTED]->(contract:Contract) WITH subject, COUNT(contract) AS numContracts\",\"filter\":[{\"app\":\"app1\",\"operator\":\"AND\",\"operands\":[{\"attribute\":\"subject.external_id\",\"operator\":\"=\",\"value\":\"$subjectId\"},{\"attribute\":\"numContracts\",\"operator\":\">\",\"value\":1}]}]},\"allowed_reads\":{\"nodes\":[\"subject.*\"],\"aggregate_values\":[\"numContracts\"]}}",
  "status": "ACTIVE",
  "tags": []
}

Request to read the CIQ Policy configuration using REST.

policy_request.jsonJson
{
  "id": "your_policy_configuration_gid"
}

Step 3

Create a CIQ Query in the context of the policy to retrieve the designated properties.

knowledge_query.jsonJson
{
  "nodes": [
    "subject.external_id"
  ],
  "aggregate_values": [
    "numContracts"
  ]
}

Request to create a CIQ Query configuration using REST.

POST https://eu.api.indykite.com/configs/v1/knowledge-queriesJson
{
  "project_id": "your_project_gid",
  "description": "description of knowledge query",
  "display_name": "knowledge query name",
  "name": "knowledge-query-name",
  "policy_id": "your_policy_gid",
  "query": "{\"nodes\":[\"subject.external_id\"],\"aggregate_values\":[\"numContracts\"]}",
  "status": "ACTIVE"
}

Read the CIQ Query Configuration.

GET https://eu.api.indykite.com/configs/v1/knowledge-queries/{id}Json
{
  "id": "your_knowledge_query_configuration_gid"
}

Step 4

Run a CIQ Execution to get the designated information.

POST https://eu.api.indykite.com/contx-iq/v1/executeJson
{
  "id": "knowledge_query_gid",
  "input_params": {
    "subjectId": "alice"
  },
  "page_token": 1
}

CIQ Execution response.

response.jsonJson
{
  "data": [
    {
      "nodes": {
        "subject.external_id": "alice"
      },
      "aggregate_values": {
        "numContracts": 3
      }
    }
  ]
}

API Endpoints

/capture/v1/nodes
/capture/v1/relationships
/configs/v1/authorization-policies
/configs/v1/knowledge-queries
/contx-iq/v1/execute
View OpenAPI docs

Related Guides

Contx IqSandbox

Tags

ContX IQ PolicyContX IQ QueryContX IQ ExecutionAggregationCOUNTWHEREWITH

Related Resources

ContX IQ: Query License Numbers a Person Can Access

ContX IQPython

ContX IQ: Retrieve Payment Methods for Contracted Vehicle Users

ContX IQPython

ContX IQ: Grant Unrestricted READ Access to a Node Category

ContX IQJson

ContX IQ: Create Nodes and Relationships via Authorized Write Query

ContX IQJson

ContX IQ: Upsert Relationships Between Existing Nodes

ContX IQJson

ContX IQ: Delete Nodes and Their Relationships via Authorized Query

ContX IQJson

ContX IQ: Loyalty Program - Retrieve Payment Method from License Plate

ContX IQJson

ContX IQ: Connect System Nodes (_Application) to Business Data

ContX IQJson

ContX IQ: Complete CRUD Workflow with _Application as Subject

ContX IQJson

ContX IQ: Create a User Node from an Access Token and Authorize Through Organization Membership

ContX IQJson