Query Service & Analytics

The Query Service provides powerful filtering, sorting, and analytics capabilities for objects in Terragnos Core. Use simple DTO-based queries or the advanced JSON DSL for complex analytics workloads.

Query Endpoints

Simple DTO Queries

For basic filtering, use the DTO-based endpoint:

GET /v1/queries/objects?typeId=traffic-signal&limit=25

Query parameters:

• typeId – Filter by object type
• status – Filter by status
• limit – Maximum results (default: 100)
• offset – Pagination offset
• sortBy – Field to sort by
• sortOrder – asc or desc

Advanced JSON DSL

For complex queries, use the JSON DSL:

POST /v1/queries/objects/run
Content-Type: application/json

{
  "filters": [...],
  "sorts": [...],
  "limit": 100,
  "offset": 0
}

Filter DSL

Attribute Filters

{
  "field": "attributes.signalType",
  "operator": "equals",
  "value": "standard"
}

Operators:

• equals (or eq) – Exact match
• notEquals (or ne) – Not equal
• in – Value in array
• notIn – Value not in array
• greaterThan (or gt) – Numeric comparison
• greaterThanOrEqual (or gte) – Numeric comparison
• lessThan (or lt) – Numeric comparison
• lessThanOrEqual (or lte) – Numeric comparison
• contains – String contains substring
• startsWith – String starts with
• endsWith – String ends with
• exists – Field exists
• notExists – Field doesn't exist
• isNull – Field is null
• isNotNull – Field is not null

Spatial Filters

{
  "field": "geometry",
  "operator": "within",
  "value": {
    "type": "Polygon",
    "coordinates": [[[12.0, 56.0], [13.0, 56.0], [13.0, 57.0], [12.0, 57.0], [12.0, 56.0]]]
  }
}

Spatial operators:

• within – Geometry is within bounds
• contains – Geometry contains bounds
• intersects – Geometry intersects bounds
• dwithin – Within distance (meters)
• bbox – Bounding box intersection (minX, minY, maxX, maxY)

Combined Filters

{
  "operator": "and",
  "filters": [
    {
      "field": "typeId",
      "operator": "equals",
      "value": "traffic-signal"
    },
    {
      "field": "attributes.status",
      "operator": "equals",
      "value": "active"
    },
    {
      "field": "geometry",
      "operator": "within",
      "value": {...}
    }
  ]
}

Logical operators:

• and – All filters must match
• or – Any filter must match
• not – Negate a filter

Nested logical operators:

{
  "operator": "or",
  "filters": [
    {
      "operator": "and",
      "filters": [
        {"field": "typeId", "operator": "equals", "value": "signal-a"},
        {"field": "attributes.status", "operator": "equals", "value": "active"}
      ]
    },
    {
      "operator": "and",
      "filters": [
        {"field": "typeId", "operator": "equals", "value": "signal-b"},
        {"field": "attributes.priority", "operator": "greaterThan", "value": 5}
      ]
    }
  ]
}

Sorting

{
  "sorts": [
    {
      "field": "attributes.priority",
      "order": "desc"
    },
    {
      "field": "createdAt",
      "order": "asc"
    }
  ]
}

Sort by multiple fields. Earlier sorts take precedence.

Complete Query Example

{
  "filters": [
    {
      "operator": "and",
      "filters": [
        {
          "field": "typeId",
          "operator": "equals",
          "value": "inspection-request"
        },
        {
          "field": "attributes.priority",
          "operator": "greaterThan",
          "value": 5
        },
        {
          "field": "attributes.status",
          "operator": "in",
          "value": ["pending", "in-progress"]
        },
        {
          "field": "geometry",
          "operator": "dwithin",
          "value": {
            "type": "Point",
            "coordinates": [19.04, 47.49]
          },
          "distanceMeters": 1000
        }
      ]
    }
  ],
  "sorts": [
    {
      "field": "attributes.priority",
      "order": "desc"
    },
    {
      "field": "createdAt",
      "order": "asc"
    }
  ],
  "limit": 50,
  "offset": 0
}

Graph Queries

Include related objects in query results:

{
  "filters": [...],
  "graph": {
    "objectIds": ["object-123"],
    "maxDepth": 2,
    "relationTypes": ["contains", "supplies"],
    "relationDirection": "all"
  }
}

Graph options:

• objectIds – Starting objects (if not provided, uses query results)
• maxDepth – Maximum relation depth to traverse
• relationTypes – Filter by relation types
• relationDirection – outgoing, incoming, or all

Aggregations

Calculate statistics:

{
  "filters": [...],
  "aggregations": [
    {
      "field": "attributes.priority",
      "function": "avg"
    },
    {
      "field": "typeId",
      "function": "count"
    }
  ]
}

Aggregation functions:

• count – Count of values
• sum – Sum of numeric values
• avg – Average of numeric values
• min – Minimum value
• max – Maximum value

Time-Travel Queries

Query historical data:

{
  "filters": [...],
  "asOf": "2024-01-15T10:30:00Z"
}

Returns object state at the specified point in time.

Performance Tips

1. Use indexes – Ensure frequently queried fields are indexed
2. Limit results – Always set reasonable limit values
3. Filter early – Apply filters before sorting/aggregation
4. Use spatial indexes – Spatial queries benefit from GIST indexes
5. Cache results – Cache query results when appropriate
6. Monitor query performance – Track slow queries

Integration Examples

BI Tools

Export data for analysis:

POST /v1/queries/objects/run
{
  "filters": [...],
  "limit": 10000
}

Reporting

Generate reports:

{
  "filters": [
    {
      "field": "createdAt",
      "operator": "greaterThan",
      "value": "2024-01-01T00:00:00Z"
    }
  ],
  "aggregations": [
    {
      "field": "typeId",
      "function": "count"
    }
  ]
}

Real-time Dashboards

Query for dashboard data:

{
  "filters": [
    {
      "field": "attributes.status",
      "operator": "equals",
      "value": "active"
    }
  ],
  "sorts": [
    {
      "field": "updatedAt",
      "order": "desc"
    }
  ],
  "limit": 100
}