# 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 Sql API
  version: 1.0.0
extends: openapi/elk-stack-sql-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: 8
- target: $.paths['/_sql/close'].post
  update:
    x-apievangelist-phrasing:
      intent: Close an SQL search cursor
      effect: write
      questions:
      - How do I release an SQL pagination cursor I'm done with?
      - Can I free the resources held by an open SQL cursor before it expires?
      instructions:
      - text: Close SQL cursor {cursor}.
        slots:
          cursor: requestBody.cursor
      - text: Clear the SQL search cursor {cursor} so it stops holding resources.
        slots:
          cursor: requestBody.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql/async/delete/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete or cancel an async SQL search
      effect: destructive
      questions:
      - How do I cancel an async SQL search that is still running?
      - Can I delete the stored results of an async SQL query once I've read them?
      instructions:
      - text: Delete async SQL search {id}.
        slots:
          id: path.id
      - text: Cancel the running SQL search {id} and discard its results.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql/async/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get results of an async SQL search
      effect: read
      questions:
      - How do I fetch the results of an async SQL query I started earlier?
      - Can I get async SQL results back as CSV instead of JSON?
      instructions:
      - text: Get the results of async SQL search {id}.
        slots:
          id: path.id
      - text: Return async SQL search {id} results in {format} format.
        slots:
          id: path.id
          format: query.format
      - text: Wait up to {wait_for_completion_timeout} for async SQL search {id} to finish and return its rows.
        slots:
          id: path.id
          wait_for_completion_timeout: query.wait_for_completion_timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql/async/status/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of an async SQL search
      effect: read
      questions:
      - Is my async SQL search still running or has it completed?
      - How can I check an async SQL search's progress without downloading its results?
      instructions:
      - text: Check the status of async SQL search {id}.
        slots:
          id: path.id
      - text: Tell me whether SQL search {id} is still running.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql'].get
  update:
    x-apievangelist-phrasing:
      intent: Run an SQL query with a GET request
      effect: read
      questions:
      - Can I send an SQL query to Elasticsearch using a GET request with a body?
      - Which output formats does a GET SQL query support?
      instructions:
      - text: Using GET, run the SQL query {query}.
        slots:
          query: requestBody.query
      - text: Send a GET request running {query} and return {fetch_size} rows per page.
        slots:
          query: requestBody.query
          fetch_size: requestBody.fetch_size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an SQL query against Elasticsearch
      effect: read
      questions:
      - How do I query my Elasticsearch indices with SQL?
      - Can I page through large SQL results with a cursor?
      - Is it possible to set a time zone for date handling in an SQL query?
      instructions:
      - text: Run the SQL query {query}.
        slots:
          query: requestBody.query
      - text: Execute {query} in time zone {time_zone} and return the results as {format}.
        slots:
          query: requestBody.query
          time_zone: requestBody.time_zone
          format: query.format
      - text: Fetch the next page of SQL results with cursor {cursor}.
        slots:
          cursor: requestBody.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql/translate'].get
  update:
    x-apievangelist-phrasing:
      intent: Translate SQL into Query DSL via GET
      effect: read
      questions:
      - Can I use a GET request to see the Query DSL that an SQL statement becomes?
      - Does the GET translate endpoint accept a filter alongside the SQL?
      instructions:
      - text: With a GET request, translate {query} into Query DSL.
        slots:
          query: requestBody.query
      - text: Via GET, show the search request generated for SQL {query}.
        slots:
          query: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_sql/translate'].post
  update:
    x-apievangelist-phrasing:
      intent: Translate SQL into Elasticsearch Query DSL
      effect: read
      questions:
      - How do I convert an SQL statement into the equivalent Elasticsearch search request?
      - What Query DSL does my SQL WHERE clause produce?
      instructions:
      - text: Translate the SQL {query} into an Elasticsearch search request.
        slots:
          query: requestBody.query
      - text: Convert SQL {query} to Query DSL using time zone {time_zone}.
        slots:
          query: requestBody.query
          time_zone: requestBody.time_zone
      method: generated
      generated: '2026-09-26'