Quickstart (5m)

This quickstart guide will help you set up and use topk in less than 5 minutes. You’ll learn how to create a collection, add documents, and perform searches using semantic search, keyword matching, and metadata filtering.

​

1. Install the SDK

The TopK SDK offers convenient programming interfaces to interact with the TopK API. You can install the SDK using the package managers listed below.

Choose your preferred language to install the SDK:

pip install topk-sdk

​

2. Create an API key

To get started with TopK, you need an API key. Here’s how you can get one for free:

1. Head down to the Console.
2. Create your account and generate an API key.

You’ll need this key to authenticate with the API. Make sure to keep it safe and secure.

​

3. Create your first collection

Collections are the primary data structure in TopK. They store documents and allow you to query them.

First, create a Client instance with your API key and region.

from topk_sdk import Client

client = Client(api_key="YOUR_TOPK_API_KEY", region="aws-us-east-1-elastica")

Then, create a collection, specifying a schema. The example below creates a books collection with a semantic index on the title field.

from topk_sdk.schema import text, semantic_index

client.collections().create(
    "books",
    schema={
        # `title` field must be present and will be indexed for semantic search.
        "title": text().required().index(semantic_index()),
    },
)

Note: Other fields can still be upserted even if they are not defined in the schema.

​

4. Add documents to the collection

After creating a collection, you can start adding documents to it.

A document is a JSON-style dictionary with one condition: it must have an _id field.

client.collection("books").upsert(
    [
        {"_id": "gatsby", "title": "The Great Gatsby"},
        {"_id": "1984", "title": "1984"},
        {"_id": "catcher", "title": "The Catcher in the Rye"}
    ],
)

​

5. Query your collection

Now, send your first semantic search query:

from topk_sdk.query import select, fn, match, field

results = client.collection("books").query(
    select(
        "title",
        # Perform semantic search on the `title` field
        title_similarity=fn.semantic_similarity("title", "classic American novel"),
    )
    # Sort results by the `title_similarity` field, selecting the top 10 results
    .top_k(field("title_similarity"), 10)
)

Optionally, you can call .rerank() at the end of your query to automatically improve relevance of the results. See reranking for more details.

​

6. (Optional) Clean up

To delete the entire collection:

client.collections().delete("books")

Need support or want to give some feedback? You can join our community or drop us an email at support@topk.io.

​

Next steps

Continue exploring the TopK platform: