Skip to main content
Version: TMT v5 (latest)

Query API

Introduction​

With the TMT version 5.0 release, we introduced a new query mode to retrieve document related data from the server. This will replace the existing RPC operations for receiving document related data, for example: LIST_DOCUMENT or LIST_LINKS.

First step​

To perform a query, you need to send a RPC Request with operation QUERY.

Simple example of a QUERY request:

{
	"id": "FIRST_STEP",
	"jsonrpc": "2.0",
	"method": "QUERY",
	"params": {
		"query": {
			"targetDocumentModel": "TestCase-dm",
			"projectionName": "document",
			"paging": {
				"pageSize": 10,
				"pageNumber": 0
			}
		}
	}
}
ParameterRequiredDescription
targetDocumentModel✓Document Model name for which the query should be performed.
projectionName✓Specifies which projection type should be used for the query. Pre-defined are "document", "cdd", and "document-graph" as projection names.
paging✓Specifies the pagination of the query result.
sortSpecifies the sorting of the query result documents. Data Services does not apply any sorting per default.
constraintRestricts the query result based on operators (e.g. logic operators on Document Model fields).
fieldsSpecifies which Document Model fields should be included in the query result. If not explicitly provided, all fields are included.
linksSpecifies which link documents should be included in the query result.
aggregationSpecifies a function which can be applied to the query result. Supported functions are "avg", "count", "min", "max", and "sum".
excludeSpecifies whether root documents should be excluded from the query result. This is useful when only link documents are required.

Query API Example​

Simple Example of Query list of test cases

Load a list of test cases by given query parameters.

Authorizations:
bearerAuth
header Parameters
Project-Id
required
string

Project Id or the project document reference

Subproject-Id
string

Sub Project Id or the project document reference. It might be required if you want to access the sub project's resource

Request Body schema: application/json
required
id
required
string

id of the operation

jsonrpc
required
string

must be 2.0

method
required
string

QUERY

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "FIRST_STEP",
  • "jsonrpc": "2.0",
  • "method": "QUERY",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "jsonrpc": "2.0",
  • "id": "FIRST_STEP",
  • "result": {
    }
}

Parameters details​

sort Parameter​

Defines the sorting behavior for the query result. It is possible to define the sorting based on multiple fields.

ParameterRequiredDescription
field✓Specifies the Document Model field path for which the query result should be sorted.
direction✓Specifies the order for the sorting of the query result. Options are "ASC" for ascending and "DESC" for descending.
nullHandling✓Specifies how null values should be handled for the sorting. Options are "NULLS_FIRST" and "NULLS_LAST".
ignoreCase✓Specifies if the sorting should be case-insensitive. Options are true or false.

Example: the query result entries will be sorted by the ID in descending order

"sort": [
    {
        "field": "/Root/General/Id",
        "direction": "DESC",
        "nullHandling": "NULLS_LAST",
        "ignoreCase": false
    }
]

It is recommended to use the "NULLS_LAST" option because it is more efficient in terms of performance.

paging Parameter​

Pagination starts counting from the index 0. This means the first query result entries are available on the page with the number 0.

ParameterRequiredDescription
pageNumber✓Specifies the page number to retrieve document data of the query result.
pageSize✓Specifies the amount of entries for each query result page.
"paging": {
    "pageSize":5,
    "pageNumber":1
}

constraint Parameter​

ParameterRequiredDescription
operator✓Specifies the kind of operator to be used. Field-aware operators: exact_match, simple_search, undefined_match, double_range, date_range, datefragment_range. Logic operators: and, or, not. Has operator: has.
operandsSpecifies an entity as an input for a search term. Some operators allow for combining multiple operands. It is possible to define any nested conditional structures.

Example:

"constraint": {
    "operator":"and",
    "operands":[
        {
            "operator": "exact_match",
            "field": "/Root/General/ProjectId",
            "value": "P_1"
        },
        {
            "operator": "exact_match",
            "field": "/Root/General/SubprojectId",
            "value": "SP_1"
        },
        {
            "operator": "not",
            "operand": {
                "operator": "exact_match",
                "field": "/Root/General/TestSuiteId",
                "value": "SP_1"
            }
        },
		{
            "operator": "simple_search",
            "fields": [
              "/Root/General/Title"
            ],
            "value": "Release today"
		},
		{
		    "operator": "date_range",
		    "field": "/__meta/createdAt",
		    "from": "2026-04-01T00:00:00",
		    "to": "2026-04-01T23:59:59"
		}
    ]
}

The above constraint is Simplified

Root.General.ProjectId = "P_1" AND Root.General.SubprojectId = "SP_1" AND Root.General.TestSuiteId != "SP_1"

Supported operators are:

  • And Operator
    • operator: "and"
    • operands: list of constraints which will be combined with the AND operator
  • Or Operator
    • operator: "or"
    • operands: list of constraints which will be combined with the OR operator
  • Not Operator
    • operator: "not"
    • operand: a single constraint which will be negated with the NOT operator
{
	"operator": "not",
	"operand": {
		"operator": "exact_match",
		"field": "/Root/General/TestSuiteId",
		"value": "SP_1"
	}
}
  • Has Operator
    • operator: "has"
    • relationshipModel: Specifies the Relationship Model, which document data shall be retrieved for.
    • targetRole: Specifies the target role in the relationship that will be linked to the root document. Data Services differentiates for document types "ROOT", "CHILD" and "LINK".
    • constraint: Defines a condition on the target document of the relationship, which allows for filtering of the link documents.
    • linkDocumentConstraint: Defines a condition on the link document, which allows for filtering the list of links. This is only allowed when a Link Document Model is defined for the relationship.
    • maxDepth: Relevant for self-referencing relationships. Specifies how many references will be resolved. Required when a self-referencing relationship is detected in a link during query validation.
  • Date RangeOperator
    • operator: "date_range"
    • field: Specifies the Document Model field path for which the date range operator should be applied.
    • from: Specifies the start date for the date range operator. The date needs to be provided in ISO 8601 format (e.g. "2026-04-01T00:00:00").
    • to: Specifies the end date for the date range operator. The date needs to be provided in ISO 8601 format (e.g. "2026-04-01T23:59:59").
{
    "operator": "date_range",
    "field": "/__meta/createdAt",
    "from": "2026-04-01T00:00:00",
    "to": "2026-04-01T23:59:59"
}
  • Date Fragment Range Operator
    • operator: "datefragment_range"
    • field: Specifies the Document Model field path for which the date fragment range operator should be applied.
    • from: Specifies the start date fragment for the date fragment range operator. The date fragment needs to be provided in the format "datepart:datevalue" (e.g. "year:2024").
    • to: Specifies the end date fragment for the date fragment range operator. The date fragment needs to be provided in the format "datepart:datevalue" (e.g. "year:2024").
  • Double Range Operator
    • operator: "double_range"
    • field: Specifies the Document Model field path for which the date fragment range operator should be applied.
    • from: Specifies the start date fragment for the date fragment range operator. The date fragment needs to be provided in the format "datepart:datevalue" (e.g. "year:2024").
    • to: Specifies the end date fragment for the date fragment range operator. The date fragment needs to be provided in the format "datepart:datevalue" (e.g. "year:2024").
  • Exact Match Operator: Represents an EXACT MATCH search operator. Returns all results that have fields with value that matches exactly the input value.
    • operator: "exact_match"
    • field: Specifies the Document Model field path for which the exact match operator should be applied.
    • value: Specifies the value for which the exact match operator should be applied.
    • caseSensitive?: Specifies if the exact match operator should be case-sensitive. Options are true or false. The default value is false.
{
	"operator": "exact_match",
	"field": "/Root/General/ProjectId",
	"value": "P_1"
}
  • UndefinedMatchOperator: Represents the UNDEFINED_MATCH operator that checks if a given field has value null or if it is not present.
    • operator: "undefined_match"
    • field: Specifies the Document Model field path for which the undefined match operator should be applied.
    • value: Specifies whether the field value is defined or not. Options are true (field value is defined) or false (field value is not defined).
  • SimpleSearchOperator:
    • Represents a SIMPLE SEARCH search operator.
    • Return all documents which have fields with a value that contains the input string.
    • This operator can be applied on types:
      • StringType
    • parameters:
    • operator: "simple_search"
      • fields: Specifies the Document Model field path for which the simple search operator should be applied.
      • value: Specifies the value for which the simple search operator should be applied.
{
	"operator": "simple_search",
	"fields": [
	  "/Root/General/Title"
	],
	"value": "Release today"
}

fields Parameter​

The fields parameter is part of the projection for the query result. It allows to specify the data fields which should be returned. All other Document Model fields will be ignored. Providing this parameter improves performance and reduces the result payload.

Example:

"fields":[
    "/Root/General/Id",
    "/Root/General/Title"
]

In the above example, only the fields "Id" and "Title" of the Document Model will be included in the query result. All other fields will be ignored.

The links parameter allows selecting additionally related documents in a relationship next to the query root documents. It is possible to define constraints for the link documents, which allows the filtering of such.

ParameterRequiredDescription
relationshipModel✓Specifies the Relationship Model, which document data shall be retrieved for.
targetRole✓Specifies the target role in the relationship that will be linked to the root document. Data Services differentiates for document types "ROOT", "CHILD" and "LINK".
constraintDefines a condition on the target document of the relationship, which allows for filtering of the link documents.
linkDocumentConstraintDefines a condition on the link document, which allows for filtering the list of links. This is only allowed when a Link Document Model is defined for the relationship.
fieldsSpecifies which fields of the "CHILD" documents should be included in the query result. If not explicitly provided, all fields are included.
linkDocumentFieldsSpecifies which fields of the "LINK" documents should be included in the query result. If not explicitly provided, all fields are included.
linksAllows for linking additional documents to the link documents. It is possible to define either recursive or nested structures.
maxDepthRelevant for self-referencing relationships. Specifies how many references will be resolved. Required when a self-referencing relationship is detected in a link during query validation.

See the following example for the links parameter:

  "params": {
    "query": {
      "targetDocumentModel": "TestRun-dm",
      "projectionName": "document",
      "paging": {
        "pageSize": 50,
        "pageNumber": 0
      },
      "links": {
        "relationshipModel": "TestRunTestCase-rm",
        "targetRole": "TestCase",
        "fields": [
          "/Root/General/Title",
          "/Root/General/Id",
          "/__meta/docRef"
        ],
        "constraint": {
          "operator": "exact_match",
          "field": "/Root/General/ProjectId",
          "value": "P_6"
        },
        "linkDocumentFields": [
          "/Root/General/Id",
          "/Root/General/Result",
          "/__meta/docRef"
        ],
        "maxDepth": 1
      }
    }
  }

In the above example,

  • The query is performed for the Document Model "TestRun-dm".
  • For each TestRun document in the query result, linked TestCase documents will be included in the query result based on the relationship model "TestRunTestCase-rm" and the target role "TestCase".
  • Only the fields "Title", "Id", and the document reference field will be included for the linked TestCase documents in the query result.
  • Additionally, only those TestCase documents will be included in the query result which have the value "P_1" in the field "ProjectId".
  • For the link documents, only the fields "Id", "Result", and the document reference field will be included in the query result.

Aggregation Parameter​

ParameterRequiredDescription
aggregations✓List of different aggregation operations.
function✓Specifies the type of operation to be processed. Options are "avg", "min", "max", "sum" and "count".
field✓Specifies the Document Model field for which the aggregation should be processed or grouped.
group✓Collect the aggregation results and group them based on a field.
{
  "aggregation": {
    "aggregations": [
      {
        "function": "count",
        "field": "/Root/General/Id"
      }
    ],
    "group": [
      {
        "field": "/Root/General/ProjectId"
      }
    ]
  }
}

In the example above, the test cases are counted and then grouped by ProjectId.

Migration from FilterSpec​

The old filter spec used in the LIST_DOCUMENT can be migrated to Query API constraints as follows:

Old Filter spec

"filters": [
	"Root.General.TenantId:T_1",
	"Root.General.ProjectId:P_98",
	"Root.General.SubprojectId:_",
	"Root.General.Id:C_1",
	"Root.General.Title:test",
	"~Root.General.Title:test",
	"-Root.General.Title:test",
	"Root.General.Id:(C_1 OR C_2 OR C_3)",
]

New Query API constraint:

"constraint": {
  "operator": "and",
  "operands": [
    // "Root.General.TenantId:T_1"
    {
      "operator": "exact_match",
      "field": "/Root/General/TenantId",
      "value": "T_1"
    },
    // "Root.General.ProjectId:P_98"
    {
      "operator": "exact_match",
      "field": "/Root/General/ProjectId",
      "value": "P_98"
    },
    // "Root.General.SubprojectId:_"
    {
      "operator": "exact_match",
      "field": "/Root/General/SubprojectId",
      "value": "_"
    },
    // "Root.General.Id:C_1"
    {
      "operator": "exact_match",
      "field": "/Root/General/Id",
      "value": "C_1"
    },
    // "Root.General.Title:test"
    {
      "operator": "exact_match",
      "field": "/Root/General/Title",
      "value": "test"
    },
    // "~Root.General.Title:test"
    {
      "operator": "simple_search",
      "fields": [
        "/Root/General/Title"
      ],
      "value": "test"
    },
    // "-Root.General.Title:test"
    {
      "operator": "not",
      "operand": {
        "operator": "exact_match",
        "field": "/Root/General/TestSuiteId",
        "value": "SP_1"
      }
    },
    // "Root.General.Id:(C_1 OR C_2 OR C_3)"
    {
      "operator": "or",
      "operands": [
        {
          "operator": "exact_match",
          "field": "/Root/General/Id",
          "value": "C_1"
        },
        {
          "operator": "exact_match",
          "field": "/Root/General/Id",
          "value": "C_2"
        },
        {
          "operator": "exact_match",
          "field": "/Root/General/Id",
          "value": "C_3"
        }
      ]
    }
  ]
}