Skip to content

Improve description for search_after #4226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lcawl opened this issue Apr 8, 2025 · 0 comments
Open

Improve description for search_after #4226

lcawl opened this issue Apr 8, 2025 · 0 comments

Comments

@lcawl
Copy link
Contributor

lcawl commented Apr 8, 2025

We received feedback that the description in https://www.elastic.co/docs/api/doc/elasticsearch-serverless/operation/operation-search#operation-search-body-application-json-retriever-search_after is poor:

search_after array[number | string | boolean | null]
A field value.

That documentation is derived from https://github.com/elastic/elasticsearch-specification/blob/main/specification/_global/search/SearchRequest.ts:

   /**
     * Used to retrieve the next page of hits using a set of sort values from the previous page.
     */
    search_after?: SortResults

I believe that when you use OpenAPI 3.0, however, you cannot have descriptions that are peers to re-used schemas, which is why the OpenAPI document is missing that detail:

          "search_after": {
            "$ref": "#/components/schemas/_types:SortResults"
          }

Instead, it contains only what appears in the SortResults object, which is defined in http://github.com/elastic/elasticsearch-specification/blob/main/specification/_types/sort.ts

export type SortResults = FieldValue[]

It will need to be investigated whether there's a more meaningful description that can be added (likely in the sort.ts file that is applicable to all the places where that object is re-used. Then verify that it gets properly percolated into the OpenAPI output.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant