# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elasticsearch Request & Response Specification Esql API
  version: 1.0.0
extends: openapi/elk-stack-esql-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 19
- target: $.paths['/_query/async'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an ES|QL query asynchronously
      effect: read
      questions:
      - How do I run a long ES|QL query in the background and fetch results later?
      - Can I keep async ES|QL results around after the query completes?
      - How long will an async ES|QL query wait before returning an id?
      instructions:
      - text: Run ES|QL query {query} asynchronously.
        slots:
          query: requestBody.query
      - text: Start async ES|QL query {query} and wait up to {wait_for_completion_timeout} for it to finish.
        slots:
          query: requestBody.query
          wait_for_completion_timeout: requestBody.wait_for_completion_timeout
      - text: Submit async ES|QL {query} and keep the results for {keep_alive}.
        slots:
          query: requestBody.query
          keep_alive: requestBody.keep_alive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/async/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of an async ES|QL query
      effect: read
      questions:
      - Has my async ES|QL query finished yet?
      - Can I get async ES|QL results back as CSV?
      instructions:
      - text: Get results for async ES|QL query {id}.
        slots:
          id: path.id
      - text: Fetch async ES|QL query {id} results in {format} format.
        slots:
          id: path.id
          format: query.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/async/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Cancel or delete an async ES|QL query
      effect: destructive
      questions:
      - How do I cancel an async ES|QL query that's still running?
      - Can I delete stored results of a finished async ES|QL query?
      instructions:
      - text: Delete async ES|QL query {id}.
        slots:
          id: path.id
      - text: Cancel async ES|QL query {id} and discard its stored results.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/async/{id}/stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop an async ES|QL query and keep partial results
      effect: write
      questions:
      - Can I stop an async ES|QL query and get whatever results it has so far?
      - How do I interrupt a slow ES|QL query without losing partial output?
      instructions:
      - text: Stop async ES|QL query {id} and return the results so far.
        slots:
          id: path.id
      - text: Interrupt ES|QL query {id}, dropping null columns when drop_null_columns is {drop_null_columns}.
        slots:
          id: path.id
          drop_null_columns: query.drop_null_columns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/data_source/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get ES|QL data sources by name
      effect: read
      questions:
      - How do I look up a specific ES|QL federation data source by name?
      - Can I fetch data sources matching a wildcard name pattern?
      instructions:
      - text: Get ES|QL data source {name}.
        slots:
          name: path.name
      - text: Show the data sources matching {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/data_source/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an ES|QL data source
      effect: write
      questions:
      - How do I register an external data source for ES|QL data federation?
      - Can I replace the settings of an existing ES|QL data source?
      instructions:
      - text: Create ES|QL data source {name} of type {type}.
        slots:
          name: path.name
          type: requestBody.type
      - text: Set data source {name} of type {type} with settings {settings}.
        slots:
          name: path.name
          type: requestBody.type
          settings: requestBody.settings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/data_source/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete ES|QL data sources
      effect: destructive
      questions:
      - How do I remove an ES|QL federation data source?
      - Why would deleting a data source fail with a 409 conflict?
      instructions:
      - text: Delete ES|QL data source {name}.
        slots:
          name: path.name
      - text: Remove the federation data sources {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/dataset/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get ES|QL datasets by name
      effect: read
      questions:
      - How do I look up a particular ES|QL dataset by name?
      - Can I fetch datasets using a wildcard pattern?
      instructions:
      - text: Get ES|QL dataset {name}.
        slots:
          name: path.name
      - text: Show the datasets matching {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/dataset/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an ES|QL dataset
      effect: write
      questions:
      - How do I define a dataset that points at an external data source for ES|QL?
      - Can I give an ES|QL dataset its own mappings?
      instructions:
      - text: Create dataset {name} on data source {data_source} for resource {resource}.
        slots:
          name: path.name
          data_source: requestBody.data_source
          resource: requestBody.resource
      - text: Update dataset {name} using data source {data_source}, resource {resource} and mappings {mappings}.
        slots:
          name: path.name
          data_source: requestBody.data_source
          resource: requestBody.resource
          mappings: requestBody.mappings
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/dataset/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete ES|QL datasets
      effect: destructive
      questions:
      - How do I remove an ES|QL dataset?
      - What happens if one of the datasets I ask to delete doesn't exist?
      instructions:
      - text: Delete ES|QL dataset {name}.
        slots:
          name: path.name
      - text: Remove the federation datasets {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/view/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a stored ES|QL view by name
      effect: read
      questions:
      - What query is behind a specific saved ES|QL view?
      - Can I fetch one ES|QL view by its name?
      instructions:
      - text: Get ES|QL view {name}.
        slots:
          name: path.name
      - text: Show the query stored in view {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/view/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an ES|QL view
      effect: write
      questions:
      - How do I save an ES|QL query as a reusable view?
      - Can I add a description to an ES|QL view?
      instructions:
      - text: Create ES|QL view {name} with query {query}.
        slots:
          name: path.name
          query: requestBody.query
      - text: Save view {name} for query {query} described as {description}.
        slots:
          name: path.name
          query: requestBody.query
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/view/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a stored ES|QL view
      effect: destructive
      questions:
      - How do I remove a saved ES|QL view?
      - Can I delete an ES|QL view I no longer use?
      instructions:
      - text: Delete ES|QL view {name}.
        slots:
          name: path.name
      - text: Remove the stored view {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/data_source'].get
  update:
    x-apievangelist-phrasing:
      intent: List all ES|QL data sources
      effect: read
      questions:
      - Which data sources are configured for ES|QL federation?
      - Can I list every ES|QL data source at once?
      instructions:
      - text: List all ES|QL data sources.
      - text: Show every configured federation data source.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/dataset'].get
  update:
    x-apievangelist-phrasing:
      intent: List all ES|QL datasets
      effect: read
      questions:
      - What ES|QL datasets exist in my cluster?
      - Can I see every federation dataset in one call?
      instructions:
      - text: List all ES|QL datasets.
      - text: Show every configured federation dataset.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/queries/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a running ES|QL query
      effect: read
      questions:
      - What is a particular running ES|QL query doing right now?
      - Can I inspect one in-flight ES|QL query by its id?
      instructions:
      - text: Show details of running ES|QL query {id}.
        slots:
          id: path.id
      - text: Inspect in-flight query {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/view'].get
  update:
    x-apievangelist-phrasing:
      intent: List all stored ES|QL views
      effect: read
      questions:
      - Which ES|QL views have been saved?
      - Can I list every stored ES|QL view?
      instructions:
      - text: List all ES|QL views.
      - text: Show every saved view.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query/queries'].get
  update:
    x-apievangelist-phrasing:
      intent: List running ES|QL queries
      effect: read
      questions:
      - Which ES|QL queries are currently running on the cluster?
      - Is there any long-running ES|QL query I should look at?
      instructions:
      - text: List running ES|QL queries.
      - text: Show all in-flight queries and their ids.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_query'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an ES|QL query and get results
      effect: read
      questions:
      - How do I run an ES|QL query and get the rows back right away?
      - Can I get ES|QL results as CSV or TSV?
      - Can I pass parameters into an ES|QL query instead of string building?
      instructions:
      - text: Run ES|QL query {query}.
        slots:
          query: requestBody.query
      - text: Run ES|QL {query} and return it as {format}.
        slots:
          query: requestBody.query
          format: query.format
      - text: Run ES|QL {query} with params {params} in time zone {time_zone}.
        slots:
          query: requestBody.query
          params: requestBody.params
          time_zone: requestBody.time_zone
      method: generated
      generated: '2026-09-26'