Skip to main content
Version: v0.3.1

Quickstart

Before running Quickwit search instances on your servers, you will need to create indexes, add documents, and finally launch the server. In this quick start guide, we will install Quickwit and go through these steps one by one. All the Quickwit commands used in this guide are documented in the CLI reference documentation.

Install Quickwit using Quickwit installer​

The Quickwit installer automatically picks the correct binary archive for your environment and then downloads and unpacks it in your working directory. This method works only for some OS/architectures, and you will also need to install some external dependencies.

curl -L https://install.quickwit.io | sh
cd ./quickwit-v*/
./quickwit --version

You can now move this executable directory wherever sensible for your environment and possibly add it to your PATH environment.

Use Quickwit's Docker image​

You can also pull and run the Quickwit binary in an isolated Docker container.

docker run quickwit/quickwit --version

Create your first index​

Before adding documents to Quickwit, you need to create an index configured with a JSON config file. This config file notably lets you define how to map your input documents to your index fields and whether these fields should be stored and indexed. See the index config documentation.

Let's create an index configured to receive Wikipedia articles.

# First, download the Wikipedia config from Quickwit repository.
curl -o wikipedia-index-config.yaml https://raw.githubusercontent.com/quickwit-oss/quickwit/main/config/tutorials/wikipedia/index-config.yaml

The index config defines three text fields: title, body and url. It also sets two default search fields body and title. These fields will be used for search if you do not target a specific field in your query. Please note that by default, text fields are indexed and tokenized.

And here is the complete config:

wikipedia_index_config.yaml
version: 0
index_id: wikipedia
doc_mapping:
  field_mappings:
    - name: title
      type: text
      tokenizer: default
      record: position
      stored: true
    - name: body
      type: text
      tokenizer: default
      record: position
      stored: true
    - name: url
      type: text
      tokenizer: raw

search_settings:
  # If you do not specify fields in your query, those fields will be used.
  default_search_fields: [title, body]

Now we can create the index with the command:

./quickwit index create --index-config ./wikipedia-index-config.yaml

Check that a directory ./qwdata/indexes/wikipedia has been created, Quickwit will write index files here and a quickwit.json which contains the index metadata. You're now ready to fill the index.

Let's add some documents​

Quickwit can index data from many sources. We will use a new line delimited json ndjson datasets as our data source. Let's download a bunch of wikipedia articles (10 000) in ndjson format and index it.

# Download the first 10_000 Wikipedia articles.
curl -o wiki-articles-10000.json https://quickwit-datasets-public.s3.amazonaws.com/wiki-articles-10000.json
# Index our 10k documents.
./quickwit index ingest --index wikipedia --input-path wiki-articles-10000.json

Wait one second or two and check if it worked by using search command:

./quickwit index search --index wikipedia --query "barack AND obama"

It should return 10 hits. Now you're ready to serve our search API.

Start the search service​

Quickwit provides a search REST API that can be started using the service subcommand.

./quickwit run --service searcher

Check it's working by browsing the UI at http://localhost:7280 or do a simple GET with cURL:

curl "http://127.0.0.1:7280/api/v1/wikipedia/search?query=barack+AND+obama"

You can also specify the search field with body:barack AND obama:

curl "http://127.0.0.1:7280/api/v1/wikipedia/search?query=body:barack+AND+obama"

Check out the server logs to see what's happening.

note

Don't forget to encode correctly the query params to avoid bad request (status 400).

Clean​

Let's do some cleanup by deleting the index:

./quickwit index delete --index wikipedia

Congrats! You can level up with the following tutorials to discover all Quickwit features.

TLDR​

Run the following command from within Quickwit's installation directory.

curl -o wikipedia-index-config.yaml https://raw.githubusercontent.com/quickwit-oss/quickwit/main/config/tutorials/wikipedia/index-config.yaml
./quickwit index create --index-config ./wikipedia-index-config.yaml
curl -o wiki-articles-10000.json https://quickwit-datasets-public.s3.amazonaws.com/wiki-articles-10000.json
./quickwit index ingest --index wikipedia --input-path ./wiki-articles-10000.json
./quickwit index search --index wikipedia --query "barack AND obama"
./quickwit index delete --index wikipedia

Next tutorials​