Text search

Use the text_search parameter to find entities that match free text, or that are semantically similar to a specified entity, instead of an exact query condition.

In this topic:

Keyword search

The text_search parameter returns entities that contain a given text. Use it to find entities by a term rather than by a precise value.

Pass a JSON object with a type of global and the search term in the text field:

GET /work_items?text_search={"type":"global","text":"login"}

To search for an exact phrase, wrap it in double quotation marks within the text value. You can combine a phrase with additional free tokens:

GET /work_items?text_search={"type":"global","text":"\"login fails\" timeout"}

Keyword search is supported on the following entity collections: work_items, tests, runs, run_suite_schedules, run_suite_schedule_runs, requirements, releases, milestones, tasks, environments, bdd_specs, pipelines, comments.

Find similar items

Use a context search to compare an existing source entity with other entities. Similarity search supports backlog items (features, user stories, quality stories, and defects) and manual tests. You can search for entities of the same supported type as the source entity or of a different supported type. For example, you can search for manual tests or defects similar to a specified manual test.

Licenses: Similarity search requires an Aviator license.

Similarity is determined by comparing embeddings generated from entity fields. The fields included in the embeddings depend on the entity type:

• Backlog items: name and description.
• Manual tests: name, description, and the latest test version's script.

Request syntax

Use the following syntax for similarity searches. The <collection> and <result_subtype> identify the result entities. The <source_entity_type> and <source_id> identify the entity used as the similarity source.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/<collection>?fields=id,name,subtype&query="((subtype='<result_subtype>'))"&text_search={"type":"context","similar_to":{"entity_type":"<source_entity_type>","id":"<source_id>"}}

Use the following values and combinations:

Examples

The source and result can be the same type or different supported types. The following request finds defects similar to a manual test:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?fields=id,name,subtype&query="((subtype='defect'))"&text_search={"type":"context","similar_to":{"entity_type":"test","id":"<manual_test_id>"}}

The following request finds defects similar to an existing defect:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?fields=id,name,subtype&query="((subtype='defect'))"&text_search={"type":"context","similar_to":{"entity_type":"work_item","id":"<defect_id>"}}

Response

The response contains the matching entities in relevance order. Use fields to select the fields to return and limit, offset, or other supported collection parameters to page through the results.

{
  "total_count": 1,
  "data": [
    {
      "type": "work_item",
      "subtype": "feature",
      "id": "12345",
      "name": "Related feature"
    }
  ],
  "exceeds_total_count": false
}

See also

• Retrieve and filter collections
• GET: Read all instances