title: sparql/query
description: >
  A sparql query received on the triplet store backends (e.g. query.wikidata.org)
$id: /sparql/query/1.4.0
$schema: https://json-schema.org/draft-07/schema#
type: object
additionalProperties: false
allOf:
  - $ref: /fragment/common/1.0.0#
  - properties:
      http:
        # TODO: extract and reuse an http property type
        type: object
        description: Information about the HTTP request that generated an event.
        properties:
          method:
            type: string
            description: 'The HTTP request method (GET, POST, etc.)'
          client_ip:
            type: string
            description: The HTTP client's IP address
          request_headers:
            type: object
            description: Request headers sent by the client.
            additionalProperties:
              type: string
          response_headers:
            type: object
            description: Response headers sent back to the client (when known).
            additionalProperties:
              type: string
          has_cookies:
            type: boolean
            description: True if the HTTP request has any cookies set
          status_code:
            type: integer
            description: The HTTP status code returned for this request (when known)
          response_size:
            type: integer
            description: >
              Size of the uncompressed HTTP response body in bytes. This field is used for analytics,
              and is expected to differ from the Content-Length header (when set)
      graph_name:
        type: string
        description: name of the graph being queried
      backend_host:
        type: string
        description: Hostname of sparql endpoint (blazegraph) server handling this sparql query
      namespace:
        type: string
        description: |
          Name of the database being requested
      query:
        type: string
        description: sparql query received
      query_time:
        type: integer
        description: query time
      format:
        type: string
        description: the format requested (overrides the Accept header if set)
      params:
        type: object
        description: >
          Request parameters. Usually from the HTTP query string or in the request
          body if the POST method is used. Note that the query and format params are
          not duplicated in this property.
        additionalProperties:
          type: string
      system_runtime_metrics:
        description: Runtime metrics of the service running the query.
        type: object
        required:
          - running_queries_before
          - running_queries_after
          - cpu_load_average
        properties:
          running_queries_before:
              type: integer
              description: Number of concurrent queries running before this one.
          running_queries_after:
              type: integer
              description: Number of concurrent queries running after this one.
          cpu_load_average:
              type: number
              description: >
                Average CPU load (defined as an 1 minute average of number of processes queued
                for execution and running), measured right after the query.
      performer:
        description: Represents the user that performed this query.
        type: object
        required:
          - user_text
        properties:
          user_text:
            description: The text representation of the user that performed this query.
            type: string
            minLength: 1

    required:
      - http
      - backend_host
      - namespace
      - query

examples:
  - $schema: { $ref: "#/$id" }
    meta:
      stream: sparql_query_example
      dt: '2020-07-01T00:00:00Z'
    http:
      method: GET
      has_cookies: false
      status_code: 200
    backend_host: wdqs-example1001
    graph_name: wikidata_full
    namespace: wdq
    query: example_query
    format: json
    system_runtime_metrics:
      running_queries_before: 3
      running_queries_after: 2
      cpu_load_average: 0.84
    performer:
      user_text: example_event_user