Skip to content

Add intervals query tutorial with runnable examples and advanced use cases#5585

Draft
Copilot wants to merge 3 commits intomainfrom
copilot/improve-intervals-query-page
Draft

Add intervals query tutorial with runnable examples and advanced use cases#5585
Copilot wants to merge 3 commits intomainfrom
copilot/improve-intervals-query-page

Conversation

Copy link
Contributor

Copilot AI commented Mar 23, 2026

User feedback on the intervals query reference page identified gaps: no runnable examples with sample data, no example responses, and no advanced use cases beyond what the reference already covers.

Changes

  • New tutorial solutions/search/full-text/intervals-query-tutorial.md:

    • Follows the Elastic tutorial content type template (frontmatter with description/navigation_title, "Before you begin", numbered steps, summary, next steps)
    • Full setup (index creation + bulk ingest of book synopsis data) so examples are immediately runnable in Console
    • Five progressive steps with collapsed example responses:
      1. Create index and add sample data
      2. Basic ordered proximity search (all_of + max_gaps: 0)
      3. Combined rule query using all_of + any_of for flexible unordered matching
      4. prefix rule for term-expansion proximity search — includes performance warning on expansion limits
      5. filter rule (not_containing) to exclude unwanted terms from proximity matches
    • Links to text analysis, standard analyzer, match_phrase, and full-text query reference
  • solutions/search/full-text.md: Tutorial added as a bullet under the existing "Elasticsearch query languages" section

  • solutions/toc.yml: Tutorial added to full-text navigation

Original prompt

This section details on the original issue you should resolve

<issue_title>Improvements to the Intervals query page</issue_title>
<issue_description>### Type of issue

Other

What documentation page is affected

https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-intervals-query

What happened?

Description

We’ve received user feedback that is generally positive, but includes a few actionable improvement ideas.

Feedback summary

What's working:

  • Clear definition at the top for newer users.
  • Clear parameter list (type, description, required/optional) — keep this consistent.

What could be improved:

  • Add a runnable example (e.g., an embedded interactive example or integration with a tool like Console or a code playground) to let users run the query and view sample responses/documents.
  • Helpful links to introductory concepts (like analyzer). Consider adding more contextual links if available.
  • Performance warnings (wildcards) are useful. Ensure these are consistently included in other query docs as well.
  • Having both simple and complex examples is appreciated. Check whether we can expand with one additional “advanced” use case.

Additional info

No response</issue_description>

<agent_instructions>Pay attention to the vale prose linter stylings

Peruse https://github.com/elastic/elastic-docs-skills for tips on how to do good docs PRs</agent_instructions>

Comments on the Issue (you are @copilot in this section)


📱 Kick off Copilot coding agent tasks wherever you are with GitHub Mobile, available on iOS and Android.

…ix use case

Co-authored-by: leemthompo <32779855+leemthompo@users.noreply.github.com>
Agent-Logs-Url: https://github.com/elastic/docs-content/sessions/bc2dc533-b754-466a-b219-02e150b9c84b
Copilot AI changed the title [WIP] Enhance intervals query page based on user feedback Add intervals query tutorial with runnable examples and advanced use case Mar 23, 2026
Copilot AI requested a review from leemthompo March 23, 2026 09:44
@leemthompo
Copy link
Member

@copilot this needs some polish and the cognitive boost of a stronger model like Opus 4.6

Please read, critique, and update the changes accordingly based on a thorough review

…curacy, add filter example

Major improvements:
- Restructure to follow Elastic tutorial content type template (frontmatter
  with description/navigation_title, "Before you begin", numbered steps,
  summary section)
- Replace thin sample data with richer book synopses that better demonstrate
  each feature
- Fix factual error in any_of example (doc 5 matches too, gap=2)
- Add max_gaps: 0 to outer all_of in basic example to actually enforce
  adjacency (was misleading before)
- Add Step 5: filter example with not_containing (demonstrates an additional
  advanced use case from the reference page)
- Fix prefix example: sample data now includes both "fast" and "faster" to
  meaningfully demonstrate prefix expansion
- Revert querydsl.md (sub-bullet was inconsistent with page structure)
- Simplify full-text.md change to a single bullet under existing section

Co-authored-by: leemthompo <32779855+leemthompo@users.noreply.github.com>
Agent-Logs-Url: https://github.com/elastic/docs-content/sessions/8101e7ca-119f-4e37-a334-76fe7a08b9dd
Copy link
Contributor Author

Copilot AI commented Mar 23, 2026

@copilot this needs some polish and the cognitive boost of a stronger model like Opus 4.6

Please read, critique, and update the changes accordingly based on a thorough review

Thoroughly reviewed and polished in f0a3740. Key changes:

Structural alignment with tutorial template:

  • Added navigation_title, description frontmatter
  • Restructured with "Before you begin", numbered steps (Step 1–5), Summary, Next steps
  • Added proper learning objectives ("By the end of this tutorial, you can:")

Fixed accuracy issues:

  • The basic example was missing max_gaps: 0 on the outer all_of, so "immediately before" was misleading — fixed
  • The any_of example had a wrong result set (doc 5 was incorrectly excluded; gap between text and search is exactly 2) — fixed with correct 4-document response
  • The old any_of explanation incorrectly said "performance immediately precedes machine learning in both" — wrong word order for doc 3 — removed that flawed data entirely

Better sample data and examples:

  • Replaced thin single-field "products" data with richer book synopses that naturally exercise each feature
  • The prefix example now has data with both fast and faster, actually demonstrating prefix expansion
  • Added a Step 5: filter example (not_containing) as a fourth use case — this ties back to Step 3 results to show how filters refine matches

Reverted over-reach:

  • Removed the querydsl.md sub-bullet (inconsistent with that page's structure; no other query type gets singled out)
  • Simplified full-text.md to a single bullet under the existing section instead of a separate heading

Copilot AI changed the title Add intervals query tutorial with runnable examples and advanced use case Add intervals query tutorial with runnable examples and advanced use cases Mar 23, 2026
@github-actions
Copy link
Contributor

✅ Vale Linting Results

No issues found on modified lines!


The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improvements to the Intervals query page

2 participants