Overview

Typesense is an open-source search engine designed to provide fast and typo-tolerant search capabilities. It aims to solve the common problem of users entering misspelled queries, which can lead to poor search experiences and lost opportunities. By intelligently handling typos and providing relevant search results, Typesense enhances user engagement and satisfaction, making it particularly valuable in applications where search functionality is critical.

In real-world scenarios, Typesense can be employed in e-commerce platforms, content management systems, and any application where users rely on search to find information quickly. For instance, an online bookstore can utilize Typesense to allow users to search for books even if they misspell the titles or authors. This capability significantly improves usability and retention rates.

Prerequisites

• ASP.NET Core: Familiarity with ASP.NET Core is essential for building web applications.
• Typesense Server: You need access to a running Typesense server, which can be hosted locally or on cloud platforms.
• HTTP Client Knowledge: Understanding how to make HTTP requests and handle responses in .NET Core.
• JSON Serialization: Knowledge of working with JSON data formats, as Typesense uses JSON for data interchange.

Setting Up Typesense

Before integrating Typesense into an ASP.NET Core application, you must set up the Typesense server. Typesense can be installed via Docker, which simplifies the process.

docker run -p 8108:8108 typesense/typesense:latest --data-dir /data --api-key=xyz --enable-cors

This command runs the Typesense server on port 8108 and sets an API key for authentication. The `--enable-cors` flag allows cross-origin requests, which is crucial for web applications. After launching the server, you can test it by visiting http://localhost:8108 in your browser.

Connecting to Typesense

To interact with the Typesense server, use the Typesense .NET Client, which provides a convenient way to perform CRUD operations. First, install the client via NuGet:

dotnet add package Typesense.Client

Next, configure the client in your ASP.NET Core application:

public void ConfigureServices(IServiceCollection services) {
    services.AddSingleton(new TypesenseClient(new Config {
        ApiKey = "xyz",
        Nodes = new List {
            new Node { Host = "localhost", Port = "8108", Protocol = "http" }
        },
        ConnectionTimeout = 2
    }));
}

This code snippet initializes the Typesense client with the necessary configuration, including the API key and server node details. The client is registered as a singleton, making it available throughout the application.

Creating a Collection

A collection in Typesense is akin to a table in a relational database. It holds documents that can be searched. To create a collection, define the schema, which includes the fields and their types.

public async Task CreateCollection(TypesenseClient client) {
    var schema = new CollectionSchema {
        Name = "books",
        Fields = new List {
            new Field { Name = "title", Type = "string", Index = true },
            new Field { Name = "author", Type = "string", Index = true },
            new Field { Name = "description", Type = "string" }
        ]
    };
    await client.Collections.CreateAsync(schema);
}

This method constructs a collection schema with fields for the book title, author, and description. The `Index` property determines whether the field can be searched. The method then calls the Typesense client to create the collection asynchronously.

Handling Errors

When creating a collection, it's crucial to handle potential errors, such as attempting to create a collection that already exists. Use try-catch blocks to manage exceptions effectively.

try {
    await client.Collections.CreateAsync(schema);
} catch (TypesenseException ex) {
    // Log or handle the exception
}

Indexing Documents

Once the collection is created, you can index documents. Indexing allows Typesense to store the data for efficient searching. Each document should conform to the defined schema.

public async Task IndexDocument(TypesenseClient client, Book book) {
    await client.Collections["books"].Documents.CreateAsync(book);
}

This method takes a Book object and indexes it into the previously created collection. The `CreateAsync` method sends the document to the Typesense server, where it is stored for future searches.

Document Structure

Ensure that the document structure matches the collection schema. A sample Book class may look like this:

public class Book {
    public string Id { get; set; }
    public string Title { get; set; }
    public string Author { get; set; }
    public string Description { get; set; }
}

Searching Documents

With documents indexed, you can perform searches. Typesense supports typo tolerance out of the box, allowing users to find relevant results even with misspellings.

public async Task> SearchBooks(TypesenseClient client, string query) {
    var searchParameters = new SearchParameters {
        Query = query,
        QueryBy = "title,author,description"
    };
    var result = await client.Collections["books"].Documents.SearchAsync(searchParameters);
    return result.Hits.Select(hit => hit.Document).ToList();
}

This method constructs search parameters, specifying the query and which fields to search. The `SearchAsync` method retrieves matching documents, which are then returned as a list of Book objects.

Understanding Search Parameters

Typesense offers various search parameters to refine results, such as filter, sort, and facet. For example:

searchParameters.FilterBy = "author: 'John Doe'";
searchParameters.SortBy = "title:asc";

These parameters help narrow down searches to specific authors or sort results based on title.

Edge Cases & Gotchas

While integrating Typesense, you may encounter several edge cases. One common pitfall is failing to handle duplicate documents. Typesense does not allow duplicate IDs within a collection, leading to errors if you attempt to index a document with an existing ID.

// Incorrect approach
await client.Collections["books"].Documents.CreateAsync(book); // Throws error if Id exists

To avoid this, use the CreateOrUpdateAsync method, which will update the existing document if the ID already exists.

// Correct approach
await client.Collections["books"].Documents.CreateOrUpdateAsync(book);

Performance & Best Practices

For optimal performance, consider the following best practices when using Typesense:

• Batch Indexing: Instead of indexing documents one by one, batch them to reduce the number of API calls. For example, use the `ImportAsync` method to index multiple documents at once.
• Schema Optimization: Carefully design your schema. Avoid unnecessary fields and ensure that indexed fields are relevant to search queries.
• Use Filters Wisely: Implement filters to narrow down search results, which can significantly enhance performance by reducing the amount of data processed.

Real-World Scenario

Let's consider a mini-project where we create a simple book search application. This application will allow users to search for books by title, author, or description, leveraging Typesense's typo tolerance.

public class BookController : ControllerBase {
    private readonly TypesenseClient _client;

    public BookController(TypesenseClient client) {
        _client = client;
    }

    [HttpPost("add")]
    public async Task AddBook([FromBody] Book book) {
        await IndexDocument(_client, book);
        return Ok();
    }

    [HttpGet("search")]
    public async Task Search([FromQuery] string query) {
        var results = await SearchBooks(_client, query);
        return Ok(results);
    }
}

This controller provides two endpoints: one for adding books and another for searching. The `AddBook` method indexes a new book, while the `Search` method retrieves search results based on user queries.

Conclusion

• Typesense is an effective solution for implementing typo-tolerant search in ASP.NET Core applications.
• Proper setup and configuration of the Typesense client are crucial for successful integration.
• Creating collections and indexing documents must adhere to schema definitions.
• Utilizing search parameters enhances the search experience and performance.
• Handling edge cases and following best practices are essential for a robust implementation.