Query Insights API spec

[ansjcy]

Description

API spec for query insights, more specifically, for the top n queries API.
Related API: https://opensearch.org/docs/latest/observing-your-data/query-insights/top-n-queries/

Issues Resolved

#624

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[github-actions]

Changes Analysis

Commit SHA: 9609a02
Comparing To SHA: 8255f1b

API Changes

Summary

├─┬Paths
│ └──[➕] path (2771:3)
└─┬Components
  ├──[➕] responses (28372:7)
  ├──[➕] parameters (21217:7)
  ├──[➕] schemas (50413:7)
  ├──[➕] schemas (50270:7)
  ├──[➕] schemas (50291:7)
  ├──[➕] schemas (50440:7)
  ├──[➕] schemas (50279:7)
  ├──[➕] schemas (50450:7)
  └──[➕] schemas (50422:7)

Document Element	Total Changes	Breaking Changes
components	9	0
paths	1	0

• Total Changes: 10
• Additions: 10

Report

The full API changes report is available at: https://github.com/opensearch-project/opensearch-api-specification/actions/runs/11473076195/artifacts/2091621613

API Coverage

	Before	After	Δ
Covered (%)	588 (57.59 %)	588 (57.59 %)	0 (0 %)
Uncovered (%)	433 (42.41 %)	433 (42.41 %)	0 (0 %)
Unknown	29	30	1

[github-actions]

Spec Test Coverage Analysis

Total	Tested
505	317 (62.77 %)

[dblock]

Looks good! Some asks below, iterate till tests/lints pass, add to CHANGELOG.

[ansjcy]

Hi @dblock! Thanks a lot for your review. I just pushed a commit based on your comments, let me know if it looks good to you!

[dblock]

Good. You do have to add query_insights to the CI/CD matrix.

https://github.com/opensearch-project/opensearch-api-specification/blob/main/.github/workflows/test-spec.yml#L25

[dblock]

2.18 hasn't been released so you need to have a ref and hub like below for a 2.18 build if you want to use that, but if query insights was added in 2.15 you should use 2.17, the latest stable release here.

[ansjcy]

Got it. Just updated to 2.17. Thank you!

[dblock]

👏 Good work, thanks for hanging in here with me!

[dblock]

@ansjcy I also see an intermittent CI failure, e.g. in https://github.com/opensearch-project/opensearch-api-specification/actions/runs/11487125212/job/31970965603?pr=637

I can reproduce it on a new docker start from tests/plugins/query_insights.

tests/plugins/query_insights $ docker compose up

npm run test:spec--insecure -- --tests tests/plugins/query_insights/insights/top_queries.yaml --verbose

        FAILED  Retrieve top queries by memory usage.
            PASSED  PARAMETERS
                PASSED  type
            PASSED  REQUEST BODY
            PASSED  RESPONSE STATUS
            PASSED  RESPONSE PAYLOAD BODY
            FAILED  RESPONSE PAYLOAD SCHEMA (data/top_queries/2/source/query/bool/adjust_pure_negative property is not defined in the spec)
            SKIPPED RESPONSE OUTPUT VALUES

Here's the response:

"top_queries": [
    {
      "timestamp": 1729713532744,
      "source": {
        "size": 10000,
        "query": {
          "bool": {
            "must_not": [
              {
                "exists": {
                  "field": "source",
                  "boost": 1
                }
              }
            ],
            "adjust_pure_negative": true,
            "boost": 1
          }
        }
      },
      "phase_latency_map": {
        "expand": 0,
        "query": 53,
        "fetch": 2
      },
      "search_type": "query_then_fetch",
      "indices": [
        ".opensearch-sap-log-types-config"
      ],
      "node_id": "G9AF1X_gQtWHg5VZjUVgtw",
      "total_shards": 1,
      "labels": {},
      "task_resource_usages": [
        {
          "action": "indices:data/read/search",
          "taskId": 43,
          "parentTaskId": -1,
          "nodeId": "G9AF1X_gQtWHg5VZjUVgtw",
          "taskResourceUsage": {
            "cpu_time_in_nanos": 1731501,
            "memory_in_bytes": 97912
          }
        }
      ],

#638