Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Active Queries REST API

    March 16, 2025
    + 12

    Overview

    The Active Queries REST API is provided by the Search service. This API enables you to get information about active FTS queries.

    The API schemes and host URLs are as follows:

    • http://node:8094/

    • https://node:18094/ (for secure access)

    where node is the host name or IP address of a computer running the Search service.

    Version information

    Version : 7.0

    Produces

    • application/json

    Paths

    Table of Contents

    View Active Index Queries

    GET /api/query/index/{indexName}

    Description

    Gets the details of all the active queries for any given FTS index in the system.

    Parameters

    Type Name Description Schema

    Path

    indexName
    required

    The name of a full-text index.

    string

    Query

    longerThan
    optional

    Filters the queries running beyond the given span of time.

    The duration string is a signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as 20s, -1.5h or 2h45m. Valid time units are ns, us (or µs), ms, s, m, h.

    string (duration)

    Example HTTP request

    Request 1: Find queries on the index DemoIndex1 that have been running for longer than 1 ms.

    Curl request
    shell
    Copy
    curl -XGET -H "Content-Type: application/json" \
-u <username>:<password> \
'http://localhost:8094/api/query/index/DemoIndex1?longerThan=1ms'

    Example HTTP response

    Result of request 1.

    Response 200
    json
    Copy
    {
  "status": "ok",
  "stats": {
    "total": 3,
    "successful": 3
  },
  "totalActiveQueryCount": 4,
  "filteredActiveQueries": {
    "indexName": "DemoIndex1",
    "longerThan": "1ms",
    "queryCount": 2,
    "queryMap": {
      "b91d75480470f979f65f04e8f20a1f7b-16": {
        "QueryContext": {
          "query": {
            "query": "good restraunts in france"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex1"
        },
        "executionTime": "1.059754811s"
      },
      "f76b2d51397feee28c1e757ed426ef93-2": {
        "QueryContext": {
          "query": {
            "query": "mexican food in england"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex1"
        },
        "executionTime": "1.058247896s"
      }
    }
  }
}

    View Active Node Queries

    GET /api/query

    Description

    Gets the details of all the active queries in any FTS node in a cluster. The response of the endpoint will have the entries in queryMap whose key is of the format "nodeUUID-queryID". So, the key tells that the active query, which is the value, is running on the node with uuid equal to nodeUUID and has an ID queryID on that node.

    Parameters

    Type Name Description Schema

    Query

    longerThan
    optional

    Filters the queries running beyond the given span of time.

    The duration string is a signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as 20s, -1.5h or 2h45m. Valid time units are ns, us (or µs), ms, s, m, h.

    string (duration)

    Example HTTP request

    Request 2: Find all active queries across the fts cluster.

    Curl request
    shell
    Copy
    curl -XGET -H "Content-Type: application/json" \
-u <username>:<password> \
http://localhost:8094/api/query

    Request 3: Find all queries across cluster that have been running for longer than 7s.

    Curl request
    shell
    Copy
    curl -XGET -H "Content-Type: application/json" \
-u <username>:<password> \
'http://localhost:8094/api/query?longerThan=7s'

    Example HTTP response

    Result of request 2.

    Response 200
    json
    Copy
    {
  "status": "ok",
  "stats": {
    "total": 3,
    "successful": 3
  },
  "totalActiveQueryCount": 4,
  "filteredActiveQueries": {
    "queryCount": 4,
    "queryMap": {
      "b91d75480470f979f65f04e8f20a1f7b-17": {
        "QueryContext": {
          "query": {
            "query": "good restraunts in france"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex1"
        },
        "executionTime": "2.144802122s"
      },
      "b91d75480470f979f65f04e8f20a1f7b-18": {
        "QueryContext": {
          "query": {
            "query": "decent hotel with a pool in italy"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex2"
        },
        "executionTime": "2.144712787s"
      },
      "b91d75480470f979f65f04e8f20a1f7b-19": {
        "QueryContext": {
          "query": {
            "query": "germany"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex2"
        },
        "executionTime": "2.143957727s"
      },
      "f76b2d51397feee28c1e757ed426ef93-3": {
        "QueryContext": {
          "query": {
            "query": "mexican food in england"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex1"
        },
        "executionTime": "2.14286421s"
      }
    }
  }
}

    Result of request 3.

    Response 200
    json
    Copy
    {
  "status": "ok",
  "stats": {
    "total": 3,
    "successful": 3
  },
  "totalActiveQueryCount": 3,
  "filteredActiveQueries": {
    "longerThan": "7s",
    "queryCount": 1,
    "queryMap": {
      "b91d75480470f979f65f04e8f20a1f7b-21": {
        "QueryContext": {
          "query": {
            "query": "decent hotel with a pool in italy"
          },
          "size": 10,
          "from": 0,
          "timeout": 120000,
          "index": "DemoIndex1"
        },
        "executionTime": "10.541956741s"
      }
    }
  }
}

    Cancel Active Queries

    POST /api/query/{queryID}/cancel

    Description

    Allows the user to cancel an active query that’s running longer than expected. This API is used along side the view active queries API to get the parameters queryID and uuid which will be used to cancel the query.

    Parameters

    Type Name Description Schema

    Query ID

    queryID
    required

    The active query’s ID

    integer

    Node UUID

    uuid
    optional

    Passed as a body parameter. uuid represents the active query’s coordinator node’s UUID, where the query will be canceled. This parameter allows the user to cancel a query anywhere in the system by specifying its coordinator node’s UUID.

    string (duration)

    Example HTTP request

    Request 4: Cancel a long running query with query ID 24 whose coordinator node has a uuid b91d75480470f979f65f04e8f20a1f7b.

    Curl request
    shell
    Copy
    curl -X POST -H "Content-Type: application/json" -u <username>:<password> \
http://localhost:8094/api/query/24/cancel -d \
'{ "uuid": "b91d75480470f979f65f04e8f20a1f7b" }'

    Example HTTP response

    Result of request 4.

    Response 200
    json
    Copy
    {
  "status": "ok",
  "msg": "query with ID '24' on node 'b91d75480470f979f65f04e8f20a1f7b' was aborted!"
}