openEHR Query API

openapi: 3.2.0
info:
  title: Openehr Query API
  version: latest
  contact:
    name: Specifications Editorial Committee openEHR
    url: https://specifications.openehr.org/
    email: info@openehr.org
  license:
    name: Creative Commons Attribution-NoDerivs 3.0 Unported
    url: https://creativecommons.org/licenses/by-nd/3.0/
  x-refined-note:
  - x-spec differs across the merged source definitions and was not carried
  x-status: STABLE
  description: 'Operations tagged Query across 2 of this provider''s published API definitions: openehr-definition-openapi.yml, openehr-query-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{baseUrl}/v1
  description: An example openEHR server URL.
  variables:
    baseUrl:
      default: openEHRSys.example.com
      description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
security: []
tags:
- name: Query
  x-displayName: Stored Query
  description: 'Management of stored (registered) queries in the system, including creation of new versions and retrieval by qualified name and version.


    These endpoints enable registration and lifecycle management of reusable queries available for later execution.


    Stored queries are identified by their qualified name and version.

    They can be executed using the query endpoint.'
paths:
  /definition/query/{qualified_query_name}:
    get:
      operationId: definition_query_list
      summary: List stored queries
      description: 'Retrieves list of all stored queries on the system matched by `qualified_query_name` as pattern.


        If pattern should given be in the format of `[{namespace}::]{query-name}`, and when is empty, it will be treated as "wildcard" in the search.


        Examples:

        - `GET https://openEHRSys.example.com/v1/definition/query/org.openehr` will list all versions of all queries with names starting with `org.openehr`

        - `GET https://openEHRSys.example.com/v1/definition/query/org.openehr::compositions` will list all versions of the query named `org.openehr::compositions`'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/Accept_JSON'
      responses:
        '200':
          $ref: '#/components/responses/200_QueryList'
    put:
      operationId: definition_query_store.yaml
      summary: Store a query
      description: Stores a new query, or updates an existing query on the system.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/query_type'
      - $ref: '#/components/parameters/Accept_JSON'
      - $ref: '#/components/parameters/ContentType_text'
      requestBody:
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/AQL'
            example: "SELECT c FROM\n  EHR e\n    CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1]\n      CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1]\nWHERE\n  obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp"
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_StoredQuery_stored'
        '400':
          $ref: '#/components/responses/400'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: openEHRSys.example.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /definition/query/{qualified_query_name}/{version}:
    put:
      operationId: definition_query_version_store.yaml
      summary: Store a query version
      description: Stores a query, at a specified `version`, on the system.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/query_type'
      - $ref: '#/components/parameters/Accept_JSON'
      requestBody:
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/AQL'
            example: "SELECT c FROM\n  EHR e\n    CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1]\n      CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1]\nWHERE\n  obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp"
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_StoredQuery_stored'
        '400':
          $ref: '#/components/responses/400'
        '409':
          $ref: '#/components/responses/409_StoredQuery_version'
    get:
      operationId: definition_query_version_get
      summary: Get stored query at version
      description: Retrieves the definition of a particular stored query (at specified version) and its associated metadata.
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/Accept_JSON'
      responses:
        '200':
          $ref: '#/components/responses/200_StoredQuery_get'
        '404':
          $ref: '#/components/responses/404_Query_version'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: openEHRSys.example.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /query/aql:
    get:
      operationId: query_execute_adhoc_query
      summary: Execute ad-hoc AQL
      description: 'Execute a given ad-hoc AQL query, supplied by `q` parameter, fetching `fetch` numbers of rows from `offset` and passing `query_parameters` to the underlying query engine.


        See also details on usage of query parameters.'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/q'
      - $ref: '#/components/parameters/ehr_id_Query'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/fetch'
      - $ref: '#/components/parameters/query_parameters'
      - $ref: '#/components/parameters/Accept_JSON'
      responses:
        '200':
          $ref: '#/components/responses/200_Query'
        '400':
          $ref: '#/components/responses/400_Query'
        '408':
          $ref: '#/components/responses/408_Query'
    post:
      operationId: query_execute_adhoc_query_body
      summary: Execute ad-hoc AQL (POST)
      description: 'Execute a given ad-hoc AQL query, supplied by `q` attribute, fetching `fetch` numbers of rows from `offset` and passing `query_parameters` to the underlying query engine.


        See also details on usage of query parameters.'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/Accept_JSON'
      - $ref: '#/components/parameters/ContentType_JSON'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdhocQueryExecute'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_Query'
        '400':
          $ref: '#/components/responses/400_Query'
        '408':
          $ref: '#/components/responses/408_Query'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: openEHRSys.example.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /query/{qualified_query_name}:
    get:
      operationId: query_execute_stored_query
      summary: Execute stored AQL
      description: 'Execute a stored query, identified by the supplied `qualified_query_name` (at latest version), fetching `fetch` numbers of rows from `offset` and passing `query_parameters` to the underlying query engine.


        See also details on usage of query parameters.


        Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/ehr_id_Query'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/fetch'
      - $ref: '#/components/parameters/query_parameters'
      - $ref: '#/components/parameters/Accept_JSON'
      responses:
        '200':
          $ref: '#/components/responses/200_Query'
        '400':
          $ref: '#/components/responses/400_Query'
        '404':
          $ref: '#/components/responses/404_Query'
        '408':
          $ref: '#/components/responses/408_Query'
    post:
      operationId: query_execute_stored_query_body
      summary: Execute stored AQL (POST)
      description: 'Execute a stored query, identified by the supplied `qualified_query_name` (at latest version).


        See also details on usage of query parameters.


        Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/Accept_JSON'
      - $ref: '#/components/parameters/ContentType_JSON'
      requestBody:
        description: 'Specifications for a stored AQL query execution.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_Query'
        '400':
          $ref: '#/components/responses/400_Query'
        '404':
          $ref: '#/components/responses/404_Query'
        '408':
          $ref: '#/components/responses/408_Query'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: openEHRSys.example.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
  /query/{qualified_query_name}/{version}:
    get:
      operationId: query_execute_stored_query_version
      summary: Execute stored AQL version
      description: 'Execute a stored query, identified by the supplied `qualified_query_name` (at specified `version`), fetching `fetch` numbers of rows from `offset` and passing `query_parameters` to the underlying query engine.


        See also details on usage of query parameters.


        Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/ehr_id_Query'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/fetch'
      - $ref: '#/components/parameters/query_parameters'
      - $ref: '#/components/parameters/Accept_JSON'
      responses:
        '200':
          $ref: '#/components/responses/200_Query'
        '400':
          $ref: '#/components/responses/400_Query'
        '404':
          $ref: '#/components/responses/404_Query_version'
        '408':
          $ref: '#/components/responses/408_Query'
    post:
      operationId: query_execute_stored_query_version_body
      summary: Execute stored AQL version (POST)
      description: 'Execute a stored query, identified by the supplied `qualified_query_name` (at specified `version`).


        See also details on usage of query parameters.


        Queries can be stored or, once stored, their definition can be retrieved using the definition endpoint.'
      tags:
      - Query
      parameters:
      - $ref: '#/components/parameters/qualified_query_name'
      - $ref: '#/components/parameters/version'
      - $ref: '#/components/parameters/Accept_JSON'
      - $ref: '#/components/parameters/ContentType_JSON'
      requestBody:
        description: 'Specifications for a stored AQL query execution.

          '
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Query'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/200_Query'
        '400':
          $ref: '#/components/responses/400_Query'
        '404':
          $ref: '#/components/responses/404_Query_version'
        '408':
          $ref: '#/components/responses/408_Query'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: openEHRSys.example.com
          description: The (example) server base URL prefix providing openEHR services. This may contain server name, port and base path prefix.
components:
  schemas:
    QueryName:
      title: QueryName
      type: string
      description: "The (fully qualified) name of the query (when is registered as a stored query), in a format of `[{namespace}::]{query-name}`. \nSee [Query Name](#tag/Qualified_query_name) for details on syntax.\n"
      example: org.openehr::compositions
    QueryType:
      title: QueryType
      type: string
      description: 'Query formalism type.

        '
      default: AQL
      example: AQL
    AQL:
      title: AQL
      type: string
      description: 'The given AQL query.

        '
      example: SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= $systolic_bp
    QueryList:
      title: QueryList
      type: array
      items:
        $ref: '#/components/schemas/StoredQuery'
      description: 'List of Stored Query resources.

        '
      example:
      - name: org.openehr::compositions
        type: aql
        version: 1.0.1
        saved: '2017-07-16T19:20:30.450+01:00'
        q: "SELECT c  FROM EHR e[ehr_id/value=$ehr_id] \n  CONTAINS COMPOSITION c[$compositionid] \nWHERE c/name/value = 'Vitals'"
      - name: org.openehr::compositions
        type: aql
        version: 1.1.7
        saved: '2018-06-13T09:37:20.530+01:00'
        q: "SELECT c  FROM EHR e[ehr_id/value=$ehr_id] \n  CONTAINS COMPOSITION c[$uid] \nWHERE c/name/value = 'Vitals'"
    StoredQuery:
      title: StoredQuery
      required:
      - name
      - type
      - version
      - saved
      - q
      type: object
      properties:
        name:
          $ref: '#/components/schemas/QueryName'
        type:
          $ref: '#/components/schemas/QueryType'
        version:
          $ref: '#/components/schemas/QueryVersion'
        saved:
          type: string
          format: date-time
        q:
          $ref: '#/components/schemas/AQL'
      description: 'Stored Query content meta information.

        '
      example:
        name: org.openehr::compositions
        type: aql
        version: 1.0.1
        saved: '2017-07-16T19:20:30.450+01:00'
        q: SELECT c FROM EHR e[ehr_id/value=$ehr_id] CONTAINS COMPOSITION c[$compositionid] WHERE c/name/value = 'Vitals'
    Error:
      title: Error
      required:
      - message
      - validationErrors
      type: object
      properties:
        message:
          type: string
        validationErrors:
          type: array
          items:
            type: string
          description: ''
      example:
        message: Error message
        validationErrors:
        - error1
        - error2
    QueryVersion:
      title: QueryVersion
      type: string
      description: 'The SEMVER version number of the Stored Query.

        '
      example: 1.0.1
    AdhocQueryExecute:
      title: AdhocQueryExecute
      required:
      - q
      type: object
      properties:
        q:
          $ref: '#/components/schemas/AQL'
        offset:
          $ref: '#/components/schemas/Offset'
        fetch:
          $ref: '#/components/schemas/Fetch'
        query_parameters:
          $ref: '#/components/schemas/QueryParameters'
    Offset:
      title: Offset
      type: integer
      description: 'The row number in result-set to start result-set from (`0`-based), default is `0`.

        '
      format: int32
      default: 0
      example: 10
    ResultSetColumn:
      title: RESULT_SET_COLUMN
      required:
      - name
      type: object
      properties:
        name:
          type: string
          description: "Name of the column. \nWhen column alias is not present in the AQL, a `0`-based column index is used prefixed by a hash sign (i.e. `#0`, `#1`...)\n"
        path:
          type: string
          description: 'Path from the given AQL of the specified column.

            '
      description: 'An AQL column specification (e.g. a pair of column `name` and associated AQL `path`).

        '
      example:
        name: '#0'
        path: /ehr_id/value
    ResultSet:
      title: RESULT_SET
      required:
      - rows
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/ResultSetMetadata'
        name:
          $ref: '#/components/schemas/QueryName'
        q:
          $ref: '#/components/schemas/AQL'
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ResultSetColumn'
          description: 'A set of AQL column specifications, defined in the given AQL.

            '
          example:
          - name: '#0'
            path: /ehr_id/value
          - name: startTime
            path: /context/start_time/value
          - name: systolic
            path: /data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude
          - name: cid
            path: /uid/value
          - name: '#4'
            path: /name
        rows:
          type: array
          items:
            $ref: '#/components/schemas/ResultSetRow'
          description: 'An ordered set of RESULT_SET rows.

            '
    Fetch:
      title: Fetch
      type: integer
      description: 'Number of rows to fetch (the default depends on the implementation).

        '
      format: int32
      example: 10
    ResultSetRow:
      title: RESULT_SET_ROW
      type: array
      items: {}
      description: "A set of cells representing a RESULT_SET row, one cell for each column. \nContent of a cell is `ANY` (i.e. a `OBJECT` in most programming languages).\n"
      example:
      - 81433066-c417-4813-9b29-79783e7bed23
      - '2017-02-16T13:50:11.308+01:00'
      - 140
      - 90910cf0-66a0-4382-b1f8-c0f27e81b42d::openEHRSys.example.com::1
      - _type: DV_TEXT
        value: Labs
    QueryParameters:
      title: QueryParameters
      type: object
      description: 'A set of query parameters.

        '
      example:
        ehr_id: 7d44b88c-4199-4bad-97dc-d78268e01398
        systolic_bp: 140
      additionalProperties: true
    ResultSetMetadata:
      title: ResultSetMetadata
      type: object
      properties:
        _href:
          type: string
          description: URL of the executed query (only for GET endpoint).
          format: uri
        _type:
          type: string
          description: The type of the serialized result object.
        _schema_version:
          type: string
          description: The version of the specification defining the serialized object.
        _created:
          type: string
          description: Result creation time (in the extended ISO 8601 format).
          format: date-time
        _generator:
          type: string
          description: Some identifier of the application that generated the result, useful for debugging.
        _executed_aql:
          type: string
          description: "The actual AQL query that was executed by the server, after replacing the query parameters. \nThis attribute is not mandatory, but is useful for debugging.\n"
      description: 'RESULT_SET metadata.

        '
      example:
        _href: https://openEHRSys.example.com/v1/query/org.openehr::compositions
        _type: RESULTSET
        _schema_version: 1.0.0
        _created: '2017-08-19T00:25:47.568+02:00'
        _generator: openEHRSys.ResultSets.Serialization.Json.ResultSetJsonWriter (5.0.0.0)
        _executed_aql: SELECT e/ehr_id/value, c/context/start_time/value as startTime, obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude AS systolic, c/uid/value AS cid, c/name FROM EHR e CONTAINS COMPOSITION c[openEHR-EHR-COMPOSITION.encounter.v1] CONTAINS OBSERVATION obs[openEHR-EHR-OBSERVATION.blood_pressure.v1] WHERE obs/data[at0001]/events[at0006]/data[at0003]/items[at0004]/value/magnitude >= 50
      additionalProperties: true
    Query:
      title: Query
      required:
      - offset
      - fetch
      - query_parameters
      type: object
      properties:
        offset:
          $ref: '#/components/schemas/Offset'
        fetch:
          $ref: '#/components/schemas/Fetch'
        query_parameters:
          $ref: '#/components/schemas/QueryParameters'
  headers:
    ContentType_JSON:
      schema:
        type: string
        enum:
        - application/json
    Location_Query:
      description: 'The `Location` response header indicates the URL of the Stored Query resource.

        '
      schema:
        type: string
        format: url
        example: https://openEHRSys.example.com/v1/definition/query/org.openehr::compositions/1.0.1
    ETag_RESULT_SET:
      description: 'The `ETag` (i.e. entity tag) response header is an identifier of the RESULT_SET.

        '
      schema:
        type: string
        example: W/"cdbb5db1-e466-4429-a9e5-bf80a54e120b"
  parameters:
    version:
      name: version
      in: path
      description: 'A SEMVER version number.

        This can be an exact version (e.g. `1.7.1`), or a pattern as partial prefix, in a form of `{major}` or `{major}.{minor}` (e.g. `1` or `1.0`), in which case the highest (latest) version matching the prefix will be considered.

        '
      required: true
      style: simple
      schema:
        type: string
        example: '1.0'
    qualified_query_name:
      name: qualified_query_name
      in: path
      description: 'The (fully qualified) name of the query to be executed, in a format of `[{namespace}::]{query-name}`. See [Query Name](#tag/Qualified_query_name) for details on syntax.

        '
      required: true
      style: simple
      schema:
        $ref: '#/components/schemas/QueryName'
    ContentType_text:
      name: Content-Type
      in: header
      style: simple
      schema:
        type: string
        enum:
        - text/plain
    query_type:
      name: query_type
      in: query
      description: 'Parameter indicating the query language/type.

        '
      style: form
      explode: true
      schema:
        type: string
        default: AQL
        example: AQL
    Accept_JSON:
      name: Accept
      in: header
      style: simple
      schema:
        type: string
        enum:
        - application/json
    fetch:
      name: fetch
      in: query
      description: 'Number of rows to fetch (the default depends on the implementation).

        '
      style: form
      explode: true
      schema:
        type: integer
        example: 10
    ContentType_JSON:
      name: Content-Type
      in: header
      style: simple
      schema:
        type: string
        enum:
        - application/json
    q:
      name: q
      in: query
      description: 'The AQL query to be executed.

        '
      required: true
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/AQL'
    ehr_id_Query:
      name: ehr_id
      in: query
      description: 'An optional parameter to execute the query within an EHR context.

        '
      style: form
      explode: true
      schema:
        type: string
        format: uuid
        example: 7d44b88c-4199-4bad-97dc-d78268e01398
    query_parameters:
      name: query_parameters
      in: query
      description: 'Query parameters (can appear multiple times).

        '
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/QueryParameters'
    offset:
      name: offset
      in: query
      description: 'The row number in result-set to start result-set from (`0`-based), default is `0`.

        '
      style: form
      explode: true
      schema:
        type: integer
        default: 0
        example: 10
  responses:
    '400':
      description: "`400 Bad Request` is returned when the request could not be parsed or is invalid (e.g. malformed request URL syntax, missing required header or parameter, or syntactically invalid header, parameter or content). \nThe response body MAY contain error details.\n"
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    200_QueryList:
      description: '`200 OK` is returned when the query resources are successfully retrieved.

        '
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_JSON'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryList'
    200_StoredQuery_stored:
      description: '`200 OK` is returned when the query was successfully stored.

        '
      headers:
        Location:
          $ref: '#/components/headers/Location_Query'
    409_StoredQuery_version:
      description: '`409 Conflict` is returned when a query with the given `qualified_query_name` and `version` already exists on the server.

        '
    200_StoredQuery_get:
      description: '`200 OK` is returned when the stored AQL is successfully retrieved.

        '
      headers:
        Content-Type:
          $ref: '#/components/headers/ContentType_JSON'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StoredQuery'
    404_Query_version:
      description: '`404 Not Found` is returned when a stored query with `qualified_query_name` and `version` does not exist.

        '
    404_Query:
      description: '`404 Not Found` is returned when a stored query with `qualified_query_name` does not exist.

        '
    200_Query:
      description: '`200 OK` is returned when the server is able to execute the query.

        '
      headers:
        ETag:
          $ref: '#/components/headers/ETag_RESULT_SET'
        Content-Type:
          $ref: '#/components/headers/ContentType_JSON'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResultSet'
    400_Query:
      description: '`400 Bad Request` is returned when the server was unable to execute the query due to invalid input, e.g. a required parameter is missing, or at least one of the parameters has an invalid syntax.

        '
    408_Query:
      description: '`408 Request Timeout` is returned when there is a query execution timeout (i.e. maximum query execution time reached, therefore the server aborted the execution of the query).

        '
x-refined-from:
- openehr-definition-openapi.yml
- openehr-query-openapi.yml
x-tagGroups:
- name: Resource endpoints
  tags:
  - EHR