Introduction

TopK is a hybrid retrieval engine built on object storage for 10x lower cost and massive scale. It supports dense/sparse vector search, multi-vector retrieval, powerful filtering, custom ranking, and managed inference in one API.

Get Started

Prerequisites

• TopK account (Sign up here)
• TopK API key (Get an API key here)

Hybrid Search

Simple example to get you started with TopK. Check out our guides for more complex examples.

Python SDK

1. Install Python SDK

   pip

   pip install topk-sdk
   
2. Initialize the client

   Setup the TopK client with your API key and region.

   Sync

   import os
   from topk_sdk import Client
   
   client = Client(
       api_key=os.environ["TOPK_API_KEY"],
       region=os.environ.get("TOPK_REGION", "aws-us-east-1-elastica"),
   )
   

   See available regions for a full list of supported regions.
3. Create a collection

   Sync

   client.collections().create(
     "quickstart",
     schema={
       "title": text().required().index(keyword_index()),
       "content": text().index(semantic_index()),
     }
   )
   
4. Upsert documents

   Sync

   client.collection("quickstart").upsert([
     {
         "_id": "1",
         "title": "Catcher in the Rye",
         "content": "IF YOU REALLY WANT TO HEAR about it, the first thing you'll probably want to know is ...",
         "author": "J.D. Salinger",
         "year": 1951,
     },
     {
         "_id": "2",
         "title": "1984",
         "content": "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...",
         "author": "George Orwell",
         "year": 1949,
     },
     ...
   ])
   
5. Query indexed data

   Sync

   from topk_sdk.query import select, field, fn
   
   client.collection("quickstart").query(
     select(
       # Select document fields to return
       "_id", "title", "author",
       # Compute semantic similarity of content field with the query
       similarity_score = fn.semantic_similarity(
         "content",
         "What is the meaning of life?",
       )
     )
     # Filter documents by metadata
     .filter(field("rating") >= 3.0)
     # Rank using the computed similarity score and rating
     .sort(field("rating") * field("similarity_score"), asc=False)
     # Get top 10 highest ranked documents
     .limit(10)
   )
   

   To learn more about how to use the Python SDK, see the Python SDK documentation.

JavaScript SDK

1. Install JavaScript SDK

   npm

   npm install topk-js
   
2. Initialize the client

   Setup the TopK client with your API key and region.

   import { Client } from "topk-js";
   
   const client = new Client({
     apiKey: process.env.TOPK_API_KEY!,
     region: process.env.TOPK_REGION ?? "aws-us-east-1-elastica",
   });
   

   See available regions for a full list of supported regions.
3. Create a collection

   import { text, keywordIndex, semanticIndex } from "topk-js/schema";
   
   await client.collections().create("quickstart", {
     title: text().required().index(keywordIndex()),
     content: text().index(semanticIndex()),
   });
   
4. Upsert documents

   await client.collection("quickstart").upsert([
     {
       _id: "1",
       title: "Catcher in the Rye",
       content: "IF YOU REALLY WANT TO HEAR about it, the first thing you'll probably want to know is ...",
       author: "J.D. Salinger",
       rating: 3.8,
     },
     {
       _id: "2",
       title: "1984",
       content: "It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...",
       author: "George Orwell",
       rating: 4.7,
     },
     // ...
   ]);
   
5. Query indexed data

   import { select, field, fn } from "topk-js/query";
   
   await client.collection("quickstart").query(
     select({
       title: field("title"),
       author: field("author"),
       // Compute semantic similarity of content field with the query
       similarity_score: fn.semanticSimilarity(
         "content",
         "What is the meaning of life?",
       ),
     })
     // Filter documents by metadata
     .filter(field("rating").gte(3.0))
     // Rank using the computed similarity score and rating
     .sort(field("rating").mul(field("similarity_score")), false)
     // Get top 10 highest ranked documents
     .limit(10)
   );
   

   To learn more about how to use the JavaScript SDK, see the JavaScript SDK documentation.

SQL

1. Connect

   Connect using any PostgreSQL client. Use your API key as the password.

   psql "host=<region>.sql.topk.io port=5432 user=topk password=$TOPK_API_KEY dbname=topk"
   
2. Create a collection

   CREATE TABLE quickstart (
     title   TEXT NOT NULL INDEX keyword_index(),
     content TEXT          INDEX semantic_index(),
     rating  FLOAT
   );
   
3. Upsert documents

   INSERT INTO quickstart (_id, title, content, author, rating)
   VALUES
     ('1', 'Catcher in the Rye',
      'IF YOU REALLY WANT TO HEAR about it, the first thing you''ll probably want to know is ...',
      'J.D. Salinger', 3.8),
     ('2', '1984',
      'It was a bright cold day in April, and the clocks were striking thirteen. Winston Smith, ...',
      'George Orwell', 4.7);
   
4. Query indexed data

   SELECT
     _id,
     title,
     semantic_similarity(content, 'What is the meaning of life?') AS similarity_score
   FROM quickstart
   WHERE rating >= 3.0
   ORDER BY similarity_score * rating DESC
   LIMIT 10;
   

Integrations

Python SDK

Full Python SDK reference.

JavaScript SDK

Full TypeScript/JavaScript SDK reference.

CLI

The command-line interface for TopK.

Security & Compliance

TopK is SOC 2 Type I certified. Visit the trust center for full details.

Data encryption

All data is encrypted in transit and at rest.

Access control

Role-based access control with full auditability.

Private Deployment

Deploy inside your own VPC for complete isolation and data residency. Contact us for more details.

Learn More

Architecture

Learn about TopK’s architecture and how it works.

Concepts

Discover core concepts and how they work together.