Add query documentation #80
Conversation
docs/query.md
Outdated
| | `regex:` | | Regex pattern | Matches content using a regular expression. | `regex:/foo.*bar/` | | ||
| | `repo:` | `r:` | Text (string or regex) | Filters repositories by name. | `repo:"github.com/user/project"` | | ||
| | `sym:` | | Text | Searches for symbol names. | `sym:"MyFunction"` | | ||
| | `branch:` | `b:` | Text | Searches within a specific branch. | `branch:main` | |
There was a problem hiding this comment.
Could we replace the branch: row with revision: (alias rev:), and change the description to something along the lines of "Searches within a specific branch or tag?
Note that revision isn't a zoekt field, and is instead a alias to branch that is made in the backend. The reasoning is that revision better communicates that both branches & tags are supported. It's also how we are communicating things in the schema.
docs/query.md
Outdated
| | `repo:` | `r:` | Text (string or regex) | Filters repositories by name. | `repo:"github.com/user/project"` | | ||
| | `sym:` | | Text | Searches for symbol names. | `sym:"MyFunction"` | | ||
| | `branch:` | `b:` | Text | Searches within a specific branch. | `branch:main` | | ||
| | `type:` | `t:` | `filematch`, `filename`, `file`, or `repo` | Limits result types. | `type:filematch` | |
There was a problem hiding this comment.
I've never actually seen this type prefix before - It looks like it was something Sourcegraph introduced?
I tried filematch, but that didn't seem to work.. Looking at the zoekt source, it seems like this is only used in query_proto.go, which to my understanding is also something Sourcegraph introduced since they are using GRPC and protobufs to drive their search experiences.
file, filename looks like it allows you to display the results as a list of filepaths, even when searching the content of files (example).
Queries with type repo seem like they are evaluated first. If there is a match, all files from that repo are returned. On it's own, this isn't really that useful (example), but when paired with another sub-query, can be (example).
All in all, it might make sense to omit this prefix from the docs for now until we are certain we "officially" want to support it. Curious to hear your thoughts though
docs/query.md
Outdated
| @@ -0,0 +1,265 @@ | |||
| # Zoekt Query Language Guide | |||
There was a problem hiding this comment.
nit: We might want to title to be something like "Search Query Language Guide" and modify the intro a bit to something along the lines of:
This guide explains the search query language used by Sourcebot, which is a derivative of the Zoekt query language with some minor differences. Search queries allow for combining multiple filters and expressions using logical operators, negations, and grouping. Here's how to craft queries effectively.
Reasoning: there are some differences between the prefixes we support vs. what Zoekt supports (e.g., revision:. See my other comment), so want to make sure it's clear to the reader that there isn't always a 1:1 between queries used in Sourcebot vs. queries used in regular Zoekt.
|
|
||
| A query is made up of expressions. An **expression** can be: | ||
| - A negation (e.g., `-`), | ||
| - A field (e.g., `repo:`). |
There was a problem hiding this comment.
nit: thoughts on calling this concept a "prefix"?
docs/query.md
Outdated
| ### EBNF Summary | ||
|
|
||
| ```ebnf | ||
| query = expression , { "or" , expression } ; |
There was a problem hiding this comment.
nit: does this encode the fact that expressions can also be separated by spaces?
Maybe we want something like this:
query = expression, { separator, expression } ;
seperator = " " | "or"
There was a problem hiding this comment.
I think I'll omit this for now, then write a lezer grammar for zoekt query language and integrate it into the search bar.
docs/query.md
Outdated
| - **Text Fields**: | ||
| Text fields (`content:`, `repo:`, etc.) accept: | ||
| - Strings: `"my text"` | ||
| - Regular expressions: `/my.*regex/` |
There was a problem hiding this comment.
nit: everything is always evaluated as a regular expression, so wrapping things in "/" is not needed
|
|
||
| ## Syntax Overview | ||
|
|
||
| A query is made up of expressions. An **expression** can be: |
There was a problem hiding this comment.
It's probably worth mentioning that all expressions are evaluated as regular expressions (except for certain exceptions like if a expression is wrapped in "").
| | `type:` | `t:` | `filematch`, `filename`, `file`, or `repo` | Limits result types. | `type:filematch` | | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
We should probably have a "Exact Matching" section that explains how the " " operator works to match exactly what you are looking for, instead of using regular expressions.
docs/query.md
Outdated
|
|
||
| 2. **Exclude archived repositories and match a regex**: | ||
| ```plaintext | ||
| archived:no regex:/error.*handler/ |
There was a problem hiding this comment.
same nit on / not being needed for regular expressions. Also the regex: prefix is not needed since everything is matched as regex anyways
There was a problem hiding this comment.
You need / or regex if you want to do a regex with spaces in it.
|
Please squash these if merging, the history is messed up. |
This adds sample query documentation with examples