Add "containing range" APIs to QueryCursor by maxbrunsfeld · Pull Request #4919 · tree-sitter/tree-sitter

maxbrunsfeld · 2025-10-02T19:59:28Z

Follow-up to #2085

Background

Running a query on a very large syntax tree is generally much faster if you provide a smaller range within which the query cursor should search. But the current QueryCursor::set_byte_range and ::set_point_range APIs are now always guaranteed to speed things up by the same amount for all queries. Those existing methods have the semantics that a match should only be returned if some node in the match intersects the given range. In some cases, in order to find all of the relevant matches, it's still necessary to walk a large portion of the tree, including nodes arbitrarily distant from the given range.

This is a problem when editing very large files in code editors. For example, in zed-industries/zed#4701, users are observing slowness in Zed's enclosing_bracket_ranges and suggested_indents queries when editing a large JSON document. These code paths are slow despite looking only for matches that contain the cursor's position.

Solution

This PR introduces new range-based QueryCursor APIs: set_containing_byte_range and set_containing_point_range, which have a different range-filtering semantics. These allow you to search only for matches where all nodes are fully contained within the given range. These APIs are independent of the existing range-filtering methods, and can be used in conjunction with them, for more advanced filtering.

For example, if you wanted to search for any matches that intersect line 5000, as long as they are fully contained within lines 4500-5500, you could do this:

let mut query_cursor = QueryCursor::new();
query_cursor.set_point_range(Point::new(5000, 0)..Point::new(5001, 0));
query_cursor.set_containing_point_range(Point::new(4500, 0)..Point::new(5500, 0));

The benefit of these new APIs is that they make possible a more aggressive optimization inside the query cursor, where it will definitively not descend into any syntax nodes outside of the given range.

Todo

tested Co-authored-by: Kirill Bulatov <mail4score@gmail.com> Co-authored-by: dino <dinojoaocosta@gmail.com> Co-authored-by: Max Brunsfeld <maxbrunsfeld@gmail.com> Co-authored-by: John Tur <john-tur@outlook.com>

Co-authored-by: Kirill Bulatov <mail4score@gmail.com> Co-authored-by: Max Brunsfeld <maxbrunsfeld@gmail.com> Co-authored-by: dino <dinojoaocosta@gmail.com> Co-authored-by: John Tur <john-tur@outlook.com> Co-authored-by: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com> Co-authored-by: dino <dinojoaocosta@gmail.com>

clason · 2025-10-03T07:43:49Z

Only bugfixes are backported, no API changes. We also want to clean up the master branch for a follow-up 0.26.1 release, so ideally this will go in after that.

ObserverOfTime · 2025-10-03T11:26:34Z

It's fine for this to make it into 0.26 if it's ready.

maxbrunsfeld · 2025-10-03T14:41:41Z

When this lands, we either need to get 0.26 out, or backport this. Or both. I don’t care which, but it’s not gonna work to just completely block releases at any point.

clason · 2025-10-03T15:11:07Z

That is not what's happening here (believe me, I want this feature as much as you do). But it's your project, so you do what you want; I am tired of fighting about this.

ObserverOfTime · 2025-10-03T16:30:53Z

For what it's worth I'd also like to release 0.26 soon with any PRs that are ready to ship and/or necessary:

this (when completed & CI passes)
feat(bindings): add Java bindings #4681
ci(release): enable trusted publishing & attestations #4899
Test Refactor #4908
feat(bindings): add byproducts to cmake #4915 (?)
a PR that fixes or removes --emit=lib (feat: Only evaluate grammar.js to grammar.json #4601)

I think we've delayed it long enough.

maxbrunsfeld · 2025-10-03T16:35:25Z

Ok, sounds good

WillLillis · 2025-10-03T17:15:07Z

I'd double check with @amaanq but it should be fine to release 0.26.1 after this lands.

@maxbrunsfeld this will have some conflicts with #4908, do you have a preference for which should go in first? I believe the test refactor is good to merge now, (unless you have any additional comments), but I'm also fine waiting on this to land first.

WillLillis · 2025-12-02T00:51:20Z

Hey @maxbrunsfeld. Do you have a timeline in mind for when this PR will be ready to go? We're hoping to publish 0.26.1 within the next week or two, and would really like to get this in if possible. If that's not enough time, we could always punt to ~~0.26.2~~0.27.0. If I or the other maintainers can do anything to help, please let me know 🙂.

Edit: I've also copied, rebased, and tried to complete this branch in a separate PR here to keep your history intact. If you'd like to work off of that feel free!

clason · 2025-12-02T07:10:05Z

we could always punt to 0.26.2.

0.27.0, since this is an API addition. CLI consumers of the API don't have Zed's freedom of ignoring distro maintainers insisting on having tree-sitter shipped as a shared system-wide library, which makes proper (semantic) versioning very important.

(This is just about the number, not the timing! Nobody is stopping us from releasing 0.27.0 one week after 0.26.1.)

maxbrunsfeld · 2025-12-02T17:37:15Z

Thank you @WillLillis. Sorry, I have gotten pulled into a different project at Zed that is taking a lot of focus, so I had to step away from this. Feel free to proceed with the release with or without landing your rebased PR.

If anyone wants to pick this up, I think the task list in the PR description is still up to date.

clason · 2025-12-03T23:08:02Z

Superseded by #5100

…es search (#39416) Part of #39594 Closes #4701 Closes #42861 Closes #44503 ~Depends on tree-sitter/tree-sitter#4919 Release Notes: - Fixed some performance bottlenecks related to syntax analysis when editing very large files --------- Co-authored-by: Kirill Bulatov <kirill@zed.dev>

…es search (zed-industries#39416) Part of zed-industries#39594 Closes zed-industries#4701 Closes zed-industries#42861 Closes zed-industries#44503 ~Depends on tree-sitter/tree-sitter#4919 Release Notes: - Fixed some performance bottlenecks related to syntax analysis when editing very large files --------- Co-authored-by: Kirill Bulatov <kirill@zed.dev>

osiewicz and others added 2 commits October 2, 2025 12:07

cli: Do not validate UTF-8 boundaries when query results are not being

3128a61

tested Co-authored-by: Kirill Bulatov <mail4score@gmail.com> Co-authored-by: dino <dinojoaocosta@gmail.com> Co-authored-by: Max Brunsfeld <maxbrunsfeld@gmail.com> Co-authored-by: John Tur <john-tur@outlook.com>

maxbrunsfeld added the ci:backport release-0.25 Backport label label Oct 2, 2025

maxbrunsfeld mentioned this pull request Oct 3, 2025

Fix slow tree-sitter query execution by limiting the range that queries search zed-industries/zed#39416

Merged

clason removed the ci:backport release-0.25 Backport label label Oct 3, 2025

clason added this to the 0.27 milestone Oct 3, 2025

ObserverOfTime removed this from the 0.27 milestone Oct 3, 2025

maxbrunsfeld added 2 commits October 6, 2025 09:43

Clean up node range tracking in query_cursor__advance

2725e84

Add context on a few error cases in loader

847737b

clason mentioned this pull request Oct 31, 2025

Tree-sitter 0.26.x release checklist #5013

Closed

9 tasks

clason added this to the 0.26 milestone Oct 31, 2025

WillLillis mentioned this pull request Dec 2, 2025

Add "containing range" APIs to QueryCursor rebased #5100

Merged

5 tasks

clason closed this Dec 3, 2025

WillLillis deleted the query-containing-range-api branch December 3, 2025 23:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add "containing range" APIs to QueryCursor#4919

Add "containing range" APIs to QueryCursor#4919
maxbrunsfeld wants to merge 4 commits intomasterfrom
query-containing-range-api

maxbrunsfeld commented Oct 2, 2025 •

edited

Loading

Uh oh!

clason commented Oct 3, 2025

Uh oh!

ObserverOfTime commented Oct 3, 2025

Uh oh!

maxbrunsfeld commented Oct 3, 2025 •

edited

Loading

Uh oh!

clason commented Oct 3, 2025 •

edited

Loading

Uh oh!

ObserverOfTime commented Oct 3, 2025 •

edited

Loading

Uh oh!

maxbrunsfeld commented Oct 3, 2025

Uh oh!

WillLillis commented Oct 3, 2025

Uh oh!

WillLillis commented Dec 2, 2025 •

edited

Loading

Uh oh!

clason commented Dec 2, 2025

Uh oh!

maxbrunsfeld commented Dec 2, 2025

Uh oh!

clason commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

maxbrunsfeld commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Solution

Todo

Uh oh!

clason commented Oct 3, 2025

Uh oh!

ObserverOfTime commented Oct 3, 2025

Uh oh!

maxbrunsfeld commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clason commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ObserverOfTime commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maxbrunsfeld commented Oct 3, 2025

Uh oh!

WillLillis commented Oct 3, 2025

Uh oh!

WillLillis commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clason commented Dec 2, 2025

Uh oh!

maxbrunsfeld commented Dec 2, 2025

Uh oh!

clason commented Dec 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

maxbrunsfeld commented Oct 2, 2025 •

edited

Loading

maxbrunsfeld commented Oct 3, 2025 •

edited

Loading

clason commented Oct 3, 2025 •

edited

Loading

ObserverOfTime commented Oct 3, 2025 •

edited

Loading

WillLillis commented Dec 2, 2025 •

edited

Loading