GitHub Issues search has evolved far beyond its simple beginnings. With the introduction of nested queries and boolean operators, developers can now pinpoint exactly the issues they care about with remarkable precision. This Q&A breaks down what changed, how it works, and what it means for your daily workflow.
What new capabilities does GitHub Issues search now offer?
GitHub Issues search now supports constructing queries with logical AND and OR operators across all fields, along with nested parentheses for grouping. This means you can create complex, precise searches like is:issue state:open author:rileybroughten (type:Bug OR type:Epic) to find open issues authored by a specific person that are either bugs or epics. Previously, queries were limited to a flat list of terms joined implicitly by AND. Now you can mix operators arbitrarily, giving you granular control over the results set.
How did GitHub ensure backward compatibility and maintain performance?
Backward compatibility was a top priority. Every existing search query had to continue working exactly as before. The team achieved this by replacing the old search module, IssuesQuery, with a new one called ConditionalIssuesQuery. This new module is designed to handle nested queries while also supporting all previous flat query formats. Performance under high query volume was maintained by carefully rewriting how queries are parsed and mapped to Elasticsearch. The team optimized the Elasticsearch query documents to avoid performance regressions, even for deeply nested boolean logic.
What was the previous limitation of Issues search?
Before this upgrade, Issues search only supported a simple, flat structure. All terms in a query were implicitly joined by a logical AND. For example, assignee:@me label:support new-project would return issues assigned to you and labeled support and containing the text “new-project.” There was no way to express OR across different fields or to nest conditions. Users could only use OR for label values by separating them with commas, a feature added in 2021. This limitation frustrated developers who needed to find issues matching multiple alternative criteria.
Can you give an example of a nested boolean query in action?
Sure! Consider this query: is:issue state:open author:rileybroughten (type:Bug OR type:Epic). It returns all open issues authored by rileybroughten that are either a bug or an epic. The parentheses group the OR condition, while the other terms are joined by an implied AND. You can nest multiple levels: label:bug (priority:high OR priority:critical) (assignee:@me OR assignee:@team). This flexibility lets you create highly specific searches without cluttering your query with multiple simple searches.
What technical changes were made to the search module?
The core change was swapping out the IssuesQuery module for the new ConditionalIssuesQuery module. This required a complete rewrite of IssueQuery, the component that parses query strings and maps them into Elasticsearch queries. The new parser understands boolean operators and parentheses, building an abstract syntax tree (AST) that accurately represents the user’s intent. This AST is then converted into a nested Elasticsearch query document that respects the boolean logic. The rewrite also ensured that all existing query formats continue to work without modification.
How does a search query flow through the system?
Every search goes through three stages:
- Parse: The user’s input string is broken down into a structured representation—an AST in the case of nested queries.
- Query: The parsed structure is transformed into an Elasticsearch query document, then sent to Elasticsearch for execution.
- Normalize: The JSON results from Elasticsearch are mapped into Ruby objects. Results are pruned to remove records that have been deleted since the query ran.
This three-stage pipeline remains the same as before, but the parsing and query stages were significantly enhanced to handle boolean operators and nesting.
How did GitHub respond to user feedback over the years?
For nearly a decade, the developer community repeatedly asked for more flexible issue search. In 2021, GitHub shipped an initial enhancement that allowed OR-style search using comma-separated values in the label field. For example, label:support,question would find issues with either label. However, this only worked for labels. Users continued requesting cross-field boolean operators. GitHub listened and began work on the full nested query solution. The result is the current feature, which brings decades-old feature requests to life and significantly improves the search experience for millions of developers.