Step-by-Step Guide to Using Typesense: A Beginners Tutorial

63 views

Absolutely, I'd be happy to get you started with a Typesense tutorial! Typesense is an open-source search engine specifically designed for providing fast and relevant search results for structured data. It's particularly known for its ease of use and relevance in applications requiring full-text search capabilities.

Here’s a step-by-step tutorial to get you up and running with Typesense:

1. Setting Up Typesense

a. Prerequisites

  • Ensure you have Docker installed (for a simple setup).

b. Running Typesense with Docker

To quickly get Typesense up and running, you can use Docker. Open your terminal and run:

docker run -p 8108:8108 -v/tmp/typesense-data:/data typesense/typesense:latest \
--data-dir /data --api-key=xyz --listen-port=8108

2. Configuring Typesense

a. Create a Configuration File (Optional)

You can specify configurations through a config.json file, but it's optional for quick setups.

3. Setting Up a Collection

A collection in Typesense is analogous to a table in a traditional database.

a. Define a Schema

Create a schema for your collection:

{
  "name": "books",
  "fields": [
    {"name": "title", "type": "string"},
    {"name": "author", "type": "string"},
    {"name": "publication_year", "type": "int32"},
    {"name": "genre", "type": "string"}
  ],
  "default_sorting_field": "publication_year"
}

b. Create the Collection

Use curl to create the collection via a POST request:

curl -X POST "http://localhost:8108/collections" \
-H "X-TYPESENSE-API-KEY: xyz" \
-H "Content-Type: application/json" \
-d '{
  "name": "books",
  "fields": [
    {"name": "title", "type": "string"},
    {"name": "author", "type": "string"},
    {"name": "publication_year", "type": "int32"},
    {"name": "genre", "type": "string"}
  ],
  "default_sorting_field": "publication_year"
}'

4. Indexing Documents

Now that the collection is set up, you can start adding documents.

curl -X POST "http://localhost:8108/collections/books/documents" \
-H "X-TYPESENSE-API-KEY: xyz" \
-H "Content-Type: application/json" \
-d '{
  "title": "The Catcher in the Rye",
  "author": "J.D. Salinger",
  "publication_year": 1951,
  "genre": "Fiction"
}'

5. Performing Search Queries

You can perform search queries against the indexed documents.

curl "http://localhost:8108/collections/books/documents/search?q=J.D.%20Salinger&query_by=author" \
-H "X-TYPESENSE-API-KEY: xyz"

6. Client Libraries

Typesense also provides client libraries for various programming languages which can be used to interact with the Typesense server programmatically. For instance, to use the JavaScript client:

npm install typesense

const Typesense = require('typesense');

let client = new Typesense.Client({
  nodes: [{
    host: 'localhost',
    port: '8108',
    protocol: 'http'
  }],
  apiKey: 'xyz',
  connectionTimeoutSeconds: 2
});

// Perform a search
client.collections('books')
       .documents()
       .search({q: 'Salinger', query_by: 'author'})
       .then((searchResults) => {
         console.log(searchResults);
       });

Conclusion

This tutorial covers the basics of setting up, configuring, and using Typesense. For advanced configurations and features, such as multi-tenancy, API authentication, and clustering, you should refer to the Typesense documentation.

Happy coding!