SQL Query Management

Manage Suggestions query

Endpoints

• Execute query to retrieve distinct values for a column. The response is a unique UUID which is supposed to be used for requesting results of the query.

  • Path: /api/chf/tables/suggestions

  • Method: POST

  • Request body:

    {
      [mandatory] "column": "ip_client",
      [optional] "from_timestamp": 1775509037,
      [optional] "to_timestamp": 1775510837,
      [optional] "sort_order": "asc",
      [optional] "limit": 1000,
      [optional] "settings":
      {
          "max_execution_time": 5.0,
          "timeout_overflow_mode": "throw"
      }
    }

  • Response:

    {
      "message": "Success",
      "data": {
        "uuid": "c8144dc6-8aa0-ae89-1550-542cff5c3bab"
      }
    }

  • column is the name of the column to retrieve distinct values for. Must be one of the supported columns.

  • from_timestamp and to_timestamp define the time range for the query (in seconds since epoch).

    • If neither is provided, no time range filter is applied.
    • If only from_timestamp is provided, to_timestamp defaults to the maximum value.
    • If only to_timestamp is provided, from_timestamp defaults to the minimum value.

  • sort_order specifies the sorting direction for the results. Can be either asc (ascending) or desc (descending). Default is asc.

  • limit specifies the maximum number of distinct values to return. If not provided, no limit is applied.

  • settings defines a query execution time policy. If a query exceeds the specified maximum execution time, it is interrupted, and an error is returned to the FE. Otherwise, the query will be executed again, and the results will be available as usual.

    • max_execution_time: specifies the maximum allowed time in seconds before a query is interrupted.
    • timeout_overflow_mode: controls the behavior when a query exceeds the specified max_execution_time during execution. It supports the following options:
      • throw: The query is terminated and a 412 Precondition Failed error is returned.
      • break: The query is terminated but no error is returned. When the FE requests data, the BE returns no data.
• Get next page by UUID.

  • Path: /api/chf/tables/suggestions/{uuid}

  • Method: GET

  • Path parameter:

    • uuid - received from the previous request

  • Response:

    {
      "message": "Success",
      "data": {
          "state": "no_page_no_processing",
          "page": [
              {
                  "value": "192.168.1.1"
              },
              {
                  "value": "192.168.1.2"
              },
              {
                  "value": "10.0.0.1"
              }
          ]
      }
    }

  • state - indicates the state of the query:

    • has_next - more pages are available.
    • no_page_processing - no pages available yet, but query is still processing.
    • no_page_no_processing - no more pages and query processing is complete.

  • page - array of results, each containing a single value field with the distinct value as a string.

• Delete query by UUID (interrupt processing).

  • Path: /api/chf/tables/suggestions/{uuid}

  • Method: DELETE

  • Path parameter:

    • uuid - received from the POST request

  • Response:

    {
      "message": "Successfully interrupted processing the query (c8144dc6-8aa0-ae89-1550-542cff5c3bab)"
    }

• Get list of supported columns.

  • Path: /api/chf/tables/suggestions/columns

  • Method: GET

  • Response:

    [
      "ip_client",
      "ip_server",
      "application",
      "application_tag",
      "application_sub_tag",
      "server_geoip_country_code",
      "vlan_id_first",
      "mpls_label_first",
      "dns_query",
      "dns_ip_server",
      "http_ip_server",
      "http_path",
      "http_user_agent",
      "rtp_ip_client",
      "rtp_ip_server",
      "capture_session_name",
      "capture_session_start_time",
      "port_client",
      "port_server",
      "protocol",
      "mac_client",
      "mac_server",
      "client_geoip_country_code",
      "client_geoip_asname",
      "server_geoip_asname",
      "dns_request_record_type",
      "dns_response_code",
      "http_version",
      "http_method",
      "http_uri",
      "http_response_code",
      "http_header_host",
      "http_header_server",
      "rtp_codec"
    ]

Error Responses

Example error response:

  ```json
  {
    "message": "Failed to make a query: The column 'invalid_column' is not supported for suggestions"
  }
  ```