sourcebot/docs/self-hosting/more/search-contexts.mdx

---
title: Search contexts
sidebarTitle: Search contexts (EE)
---

<Note>
This is only available in the Enterprise Edition. Please add your [license key](/self-hosting/license-key) to activate it.
</Note>

A **search context** is a user-defined grouping of repositories that helps focus searches on specific areas of your codebase, like frontend, backend, or infrastructure code. Some example queries using search contexts:

- `context:data_engineering userId` - search for `userId` across all repos related to Data Engineering. 
- `context:k8s ingress` - search for anything related to ingresses in your k8's configs.
- `( context:project1 or context:project2 ) logger\.debug` - search for debug log calls in project1 and project2 


Search contexts are defined in the `context` object inside of a [declarative config](/self-hosting/more/declarative-config). Repositories can be included / excluded from a search context by specifying the repo's URL in either the `include` array or `exclude` array. Glob patterns are supported.

## Example

Let's assume we have a GitLab instance hosted at `https://gitlab.example.com` with three top-level groups, `web`, `backend`, and `shared`:

```sh
web/
├─ admin_panel/
├─ customer_portal/
├─ pipelines/
├─ ...
backend/
├─ billing_server/
├─ auth_server/
├─ db_migrations/
├─ pipelines/
├─ ...
shared/
├─ protobufs/
├─ react/
├─ pipelines/
├─ ...
```

To make searching easier, we can create three search contexts in our [config.json](/self-hosting/more/declarative-config):
- `web`: For all frontend-related code
- `backend`: For backend services and shared APIs
- `pipelines`: For all CI/CD configurations


```json
{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "contexts": {
        "web": {
            // To include repositories in a search context,
            // you can reference them...
            "include": [
                // ... individually by specifying the repo URL.
                "gitlab.example.com/web/admin_panel/core",


                // ... or as groups using glob patterns. This is
                // particularly useful for including entire "sub-folders"
                // of repositories in one go.
                "gitlab.example.com/web/customer_portal/**",
                "gitlab.example.com/shared/react/**",
                "gitlab.example.com/shared/protobufs/**"
            ],

            // Same with excluding repositories.
            "exclude": [
                "gitlab.example.com/web/customer_portal/pipelines",
                "gitlab.example.com/shared/react/hooks/**",
            ],

            // Optional description of the search context
            // that surfaces in the UI.
            "description": "Web related repos."
        },
        "backend": { /* ... specifies backend replated repos ... */},
        "pipelines": { /* ... specifies pipeline related repos ... */ }
    },
    "connections": {
        /* ...connection definitions... */
    }
}
```

<Accordion title="Repository URL details">
    Repo URLs are expected to be formatted without the leading http(s):// prefix. For example:
    - `github.com/sourcebot-dev/sourcebot` ([link](https://github.com/sourcebot-dev/sourcebot))
    - `gitlab.com/gitlab-org/gitlab` ([link](https://gitlab.com/gitlab-org/gitlab))
    - `chromium.googlesource.com/chromium` ([link](https://chromium-review.googlesource.com/admin/repos/chromium,general))
</Accordion>


Once configured, you can use these contexts in the search bar by prefixing your query with the context name. For example:
- `context:web login form` searches for login form code in frontend repositories
- `context:backend auth` searches for authentication code in backend services
- `context:pipelines deploy` searches for deployment configurations

![Example](/images/search_contexts_example.png)

Like other prefixes, contexts can be negated using `-` or combined using `or`:
- `-context:web` excludes frontend repositories from results
- `( context:web or context:backend )` searches across both frontend and backend code

See [this doc](/docs/more/syntax-reference) for more details on the search query syntax.

## Schema reference

<Accordion title="Reference">
```json
{
    "type": "object",
    "description": "Search context",
    "properties": {
    "include": {
        "type": "array",
        "description": "List of repositories to include in the search context. Expected to be formatted as a URL without any leading http(s):// prefix (e.g., 'github.com/sourcebot-dev/sourcebot'). Glob patterns are supported.",
        "items": {
            "type": "string"
        },
        "examples": [
            [
                "github.com/sourcebot-dev/**",
                "gerrit.example.org/sub/path/**"
            ]
        ]
        },
        "exclude": {
            "type": "array",
            "description": "List of repositories to exclude from the search context. Expected to be formatted as a URL without any leading http(s):// prefix (e.g., 'github.com/sourcebot-dev/sourcebot'). Glob patterns are supported.",
            "items": {
                "type": "string"
            },
            "examples": [
                [
                    "github.com/sourcebot-dev/sourcebot",
                    "gerrit.example.org/sub/path/**"
                ]
            ]
        },
        "description": {
            "type": "string",
            "description": "Optional description of the search context that surfaces in the UI."
        }
    },
    "required": [
        "include"
    ],
    "additionalProperties": false
}
```
</Accordion>