Cadasto Query API

openapi: 3.2.0
info:
  title: Cadasto Query API
  version: latest
  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: cadasto-definition-api-openapi.json, cadasto-query-api-openapi.json. 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: cataniamc.prod.cadasto.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
  x-summary: ''
  description: 'Management of stored (registered) queries in the system.

    Actions upon resources of this group are also formally described in the I_DEFINITION_QUERY Abstract Service Model interface.


    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://cataniamc.prod.cadasto.com/v1/definition/query/org.openehr` will list all versions of all queries with names starting with `org.openehr`

        - `GET https://cataniamc.prod.cadasto.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'
      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'
      requestBody:
        content:
          text/plain:
            schema:
              $ref: '#/components/schemas/AQL'
            examples:
              default:
                value: "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_StoredQuery'
    servers:
    - url: https://{baseUrl}/v1
      description: An example openEHR server URL.
      variables:
        baseUrl:
          default: cataniamc.prod.cadasto.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: This endpoint is defined but not implemented by the server.
      tags:
      - Query
      responses:
        '501':
          description: This endpoint is not implemented.
    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'
      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: cataniamc.prod.cadasto.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'
      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
      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'
      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'
      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'
      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'
      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:
  responses:
    400_StoredQuery:
      description: "`400 Bad Request` is returned when the server was unable to store the query. \nThis could be due to incorrect request body (could not be parsed, etc), unknown query type, etc.\n"
    200_QueryList:
      description: '`200 OK` is returned when the query resources are successfully retrieved.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/QueryList'
    200_StoredQuery_get:
      description: '`200 OK` is returned when the stored AQL is successfully retrieved.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StoredQuery'
    200_StoredQuery_stored:
      description: '`200 OK` is returned when the query was successfully stored.

        '
      headers:
        Location:
          $ref: '#/components/headers/Location_Query'
    404_Query_version:
      description: '`404 Not Found` is returned when a stored query with `qualified_query_name` and `version` 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:
        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).

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

        '
  schemas:
    QueryVersion:
      title: QueryVersion
      type: string
      description: 'The SEMVER version number of the Stored Query.

        '
      examples:
      - 1.0.1
    QueryList:
      title: QueryList
      type: array
      items:
        $ref: '#/components/schemas/StoredQuery'
      description: 'List of Stored Query resources.

        '
      examples:
      - - 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'"
    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}`. \nThe `namespace` prefix is optional, and when used it should be in a form of a reverse domain name.\n"
      examples:
      - org.openehr::compositions
    AQL:
      title: AQL
      type: string
      description: 'The given AQL query.

        '
      examples:
      - 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
    QueryType:
      title: QueryType
      type: string
      description: 'Query formalism type.

        '
      default: AQL
      examples:
      - AQL
    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.

        '
      examples:
      - 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'
    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'
    Fetch:
      title: Fetch
      type: integer
      description: 'Number of rows to fetch (the default depends on the implementation).

        '
      format: int32
      examples:
      - 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"
      examples:
      - - 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
    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.

        '
      additionalProperties: true
      examples:
      - _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
    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`).

        '
      examples:
      - name: '#0'
        path: /ehr_id/value
    QueryParameters:
      title: QueryParameters
      type: object
      description: 'A set of query parameters.

        '
      additionalProperties: true
      examples:
      - ehr_id: 7d44b88c-4199-4bad-97dc-d78268e01398
        systolic_bp: 140
    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
      examples:
      - 10
    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'
    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.

            '
          examples:
          - - 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.

            '
  parameters:
    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}`.

        '
      required: true
      style: simple
      schema:
        $ref: '#/components/schemas/QueryName'
    version:
      name: version
      in: path
      description: 'A SEMVER version number.

        This can be a 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
        examples:
        - '1.0'
    query_type:
      name: query_type
      in: query
      description: 'Parameter indicating the query language/type.

        '
      style: form
      explode: true
      schema:
        type: string
        default: AQL
        examples:
        - 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
        examples:
        - 7d44b88c-4199-4bad-97dc-d78268e01398
    q:
      name: q
      in: query
      description: 'The AQL query to be executed.

        '
      required: true
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/AQL'
    fetch:
      name: fetch
      in: query
      description: 'Number of rows to fetch (the default depends on the implementation).

        '
      style: form
      explode: true
      schema:
        $ref: '#/components/schemas/Fetch'
    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:
        $ref: '#/components/schemas/Offset'
  headers:
    Location_Query:
      description: 'The `Location` response header indicates the URL of the Stored Query resource.

        '
      schema:
        type: string
        format: url
        examples:
        - https://cataniamc.prod.cadasto.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
        examples:
        - '"cdbb5db1-e466-4429-a9e5-bf80a54e120b"'
x-refined-from:
- cadasto-definition-api-openapi.json
- cadasto-query-api-openapi.json
x-tagGroups:
- name: Resource endpoints
  tags:
  - EHR
x-ext-urls: {}