Skip to content

query.md

Latest commit

 

History

History
243 lines (184 loc) · 7.41 KB

query.md

File metadata and controls

243 lines (184 loc) · 7.41 KB

Search Query Language Guide

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.

Syntax Overview

A query is made up of expressions. An expression can be:

  • A negation (e.g., -),
  • A field (e.g., repo:).
  • A grouping (e.g., parentheses ()),

Logical OR operations combine multiple expressions. The AND operator is implicit, meaning multiple expressions written together will be automatically treated as AND.

All expressions are evaluated as regular expressions unless wrapped with "".

Query Components

1. Fields

Fields restrict your query to specific criteria. Here's a list of fields and their usage:

Field Aliases Values Description Examples
archived: a: yes or no Filters archived repositories. archived:yes
case: c: yes, no, or auto Matches case-sensitive or insensitive text. case:yes content:"Foo"
content: c: Text (string or regex) Searches content of files. content:"search term"
file: f: Text (string or regex) Searches file names. file:"main.go"
fork: f: yes or no Filters forked repositories. fork:no
lang: l: Text Filters by programming language. lang:python
public: yes or no Filters public repositories. public:yes
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"
revision: rev: Text Searches within a specific branch or tag. revision:main

2. Negation

Negate an expression using the - symbol.

Examples:

  • Exclude a repository: 
    -repo:"github.com/example/repo"
  • Exclude a language: 
    -lang:javascript

3. Grouping

Group queries using parentheses () to create complex logic.

Examples:

  • Match either of two repositories: 
    (repo:repo1 or repo:repo2)
  • Find test in either python or javascript files: 
    content:test (lang:python or lang:javascript)

4. Logical Operators

Use or to combine multiple expressions.

Examples:

  • Match files in either of two languages: 
    lang:go or lang:java

and boolean operator is applied automatically when expressions are separated by a space.

5. Exact Matching

Quotes "" works to match exactly what you are looking for, instead of using regular expressions.

Examples:

  • Find test.* exactly: 
    content:"test.*"

Special Query Values

  • Boolean Values: Use yes or no for fields like archived: or fork:.

  • Text Fields: Text fields (content:, repo:, etc.) accept:

    • Strings: "my text"
    • Regular expressions: my.*regex

  • Escape Characters: To include special characters, use backslashes (\).

Examples:

  • Match the string foo"bar: 
    content:"foo\"bar"
  • Match the regex foo.*bar: 
    content:foo.*bar

Advanced Examples

  1. Search for content in Python files in public repositories:

    lang:python public:yes content:"my_function"

  2. Exclude archived repositories and match a regex:

    archived:no error.*handler

  3. Find files named README.md in forks:

    file:"README.md" fork:yes

  4. Search for a specific branch:

    branch:main content:"TODO"

  5. Combine multiple fields:

    (repo:"github.com/example" or repo:"github.com/test") lang:go

Tips

  1. Combine Filters: You can combine as many fields as needed. For instance:

    repo:"github.com/example" lang:go content:"init"

  2. Use Regular Expressions: Make complex content searches more powerful:

    content:func\s+\w+\s*\(

  3. Case Sensitivity: Use case:yes for exact matches:

    case:yes content:"ExactMatch"

  4. Match Specific File Types:

    file:".*\.go" content:"package main"

Complex Query Examples

  1. Search for functions in Go files with TODO comments

    lang:go /func .* \/\/ TODO/

    Matches Go files where functions are annotated with TODO comments.

  2. Find Python test files containing the word "assert"

    lang:python file:".*test.*\\.py" content:"assert"

    Looks for test files in Python containing assertions.

  3. Search for all README files mentioning "installation"

    file:"README.*" content:"installation"

    Matches README files across repositories containing the word "installation."

  4. Find public repositories containing "openapi" in YAML files

    file:".*\\.yaml$" content:"openapi"

    Matches YAML files mentioning "openapi."

  5. Search Java repositories for method signatures matching public static

    lang:java /public static .*\\(/

    Finds Java methods declared as public static.

  6. Find JavaScript files importing React

    lang:javascript content:"import React from 'react';"

    Matches JavaScript files importing React.

  7. Find all Markdown files mentioning "license" or "agreement"

    file:".*\\.md" (content:"license" or content:"agreement")

    Targets Markdown files containing either "license" or "agreement."

  8. Find log statements in Go files

    lang:go /"log\\.(Print|Printf|Fatal|Panic).*\\(.*\\)"/

    Matches Go log statements.

  9. Look for Python repositories containing Flask imports in their app.py file

    lang:python file:"app\\.py" content:"from flask import .*"

    Matches Flask applications.

  10. Search for JSON files containing an array of objects

    file:".*\\.json" /\\[\\s*{.*/

    Finds JSON files with object arrays.

  11. Search for Kubernetes YAML files containing kind: Deployment

    file:".*\\.yaml" content:"kind: Deployment"

    Matches Kubernetes deployment files.