Zoekt

Tier: Premium, Ultimate Offering: Self-managed Status: Beta
History
caution
This feature is in beta and subject to change without notice. For more information, see epic 9404.

Zoekt is an open-source search engine designed specifically to search for code.

With this integration, you can use exact code search instead of advanced search to search for code in GitLab. You can use regular expression and exact match modes to search for code in a group or repository.

Install Zoekt

Prerequisites:

  • You must have administrator access to the instance.

To enable exact code search in GitLab, you must have at least one Zoekt node connected to the instance. The following installation methods are supported for Zoekt:

Prerequisites:

  • You must have administrator access to the instance.
  • You must install Zoekt.

To enable exact code search in GitLab:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > Search.
  3. Expand Exact code search configuration.
  4. Select the Enable indexing for exact code search and Enable exact code search checkboxes.
  5. Select Save changes.

Index root namespaces automatically

Prerequisites:

  • You must have administrator access to the instance.

You can index both existing and new root namespaces automatically. To index all root namespaces automatically:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > Search.
  3. Expand Exact code search configuration.
  4. Select the Index root namespaces automatically checkbox.
  5. Select Save changes.

When you disable this setting:

  • Existing root namespaces remain indexed.
  • New root namespaces are no longer indexed.

Pause indexing

Prerequisites:

  • You must have administrator access to the instance.

To pause indexing for exact code search:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > Search.
  3. Expand Exact code search configuration.
  4. Select the Pause indexing for exact code search checkbox.
  5. Select Save changes.

When you pause indexing for exact code search, all changes in your repository are queued. To resume indexing, clear the Pause indexing for exact code search checkbox.

Control indexing concurrency

Prerequisites:

  • You must have administrator access to the instance.

You can set the number of concurrent indexing tasks that can be run on a Zoekt node relative to its CPU capacity.

A higher ratio allows more tasks to run concurrently, potentially improving indexing throughput at the cost of increased CPU usage. The default value is 1.0, meaning one task per CPU core.

You can adjust this value based on your Zoekt node’s performance characteristics and workload.

To set the number of concurrent indexing tasks:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select Settings > Search.
  3. Expand Exact code search configuration.

  4. In the Indexing CPU to tasks multiplier text box, enter a value.

    For example, if a Zoekt node has 4 CPU cores and the ratio is set to 1.5, the number of concurrent tasks for a node is going to be 4 * 1.5, which is 6.

  5. Select Save changes.

Troubleshooting

When working with Zoekt, you might encounter the following issues.

Namespace is not indexed

When you enable the setting, new namespaces get indexed automatically. If a namespace is not indexed automatically, inspect the Sidekiq logs to see if the jobs are being processed. Search::Zoekt::SchedulingWorker is responsible for indexing namespaces.

In a Rails console session, you can check:

  • Namespaces where Zoekt is not enabled: 

    Namespace.group_namespaces.root_namespaces_without_zoekt_enabled_namespace

  • The status of Zoekt indices: 

    Search::Zoekt::Index.all.pluck(:state, :namespace_id)

To index a namespace manually, run this command: 

namespace = Namespace.find_by_full_path('<top-level-group-to-index>')
Search::Zoekt::EnabledNamespace.find_or_create_by(namespace: namespace)