Typesense Java Client ☕ 🔍

Java client library for accessing the HTTP API of Typesense search engine.

Installation

The client is available on Maven central:

dependencies {
    implementation 'org.typesense:typesense-java:0.5.0'
}

<dependency>
    <groupId>org.typesense</groupId>
    <artifactId>typesense-java</artifactId>
    <version>0.5.0</version>
</dependency>

import org.typesense.api.*;
import org.typesense.model.*;
import org.typesense.resources.*;

Usage

Create a new client

List<Node> nodes = new ArrayList<>();
nodes.add(
  new Node(
    "http",       // For Typesense Cloud use https
    "localhost",  // For Typesense Cloud use xxx.a1.typesense.net
    "8108"        // For Typesense Cloud use 443
  )
);

Configuration configuration = new Configuration(nodes, Duration.ofSeconds(2),"<API_KEY>");

Client client = new Client(configuration);

Create a new collection

List<Field> fields = new ArrayList<>();
fields.add(new Field().name("countryName").type(FieldTypes.STRING));
fields.add(new Field().name("capital").type(FieldTypes.STRING));
fields.add(new Field().name("gdp").type(FieldTypes.INT32).facet(true).sort(true));

CollectionSchema collectionSchema = new CollectionSchema();
collectionSchema.name("Countries").fields(fields).defaultSortingField("gdp");

client.collections().create(collectionSchema);

Index a document

Map<String, Object> hmap = new HashMap<>();
hmap.put("countryName","India");
hmap.put("capital","Delhi");
hmap.put("gdp", 10);

client.collections("contryName").documents().create(hmap);

Upserting a document

Map<String, Object> hmap = new HashMap<>();
hmap.put("countryName","India");
hmap.put("capital","Delhi");
hmap.put("gdp", 5);

client.collections("contryName").documents().upsert(hmap);

Import batch of documents

ImportDocumentsParameters queryParameters = new ImportDocumentsParameters();
queryParameters.action("create");

String documentList = "{\"countryName\": \"India\", \"capital\": \"Washington\", \"gdp\": 5215}\n" +
                      "{\"countryName\": \"Iran\", \"capital\": \"London\", \"gdp\": 5215}";
// Import your document as JSONL string from a file.
client.collections("countries").documents().import_(documentList, queryParameters)

Search in a collection

SearchParameters searchParameters = new SearchParameters()
                                        .q("tokoyo")
                                        .queryBy("countryName,capital")
                                        .prefix("true,false");
SearchResult searchResult = client.collections("countries").documents().search(searchParameters);

Update a document

Map<String, Object> hmap = new HashMap<>();
hmap.put("gdp", 8);
client.collections("countries").documents("28").update(hmap);

Retrieve a document

client.collections("countries").documents("28").retrieve();

Delete a document

client.collections("countries").documents("28").delete();

Delete documents using query

DeleteDocumentsParameters deleteDocumentsParameters = new DeleteDocumentsParameters();
deleteDocumentsParameters.filterBy("gdp:=[2,8]");
deleteDocumentsParameters.batchSize(10);

Retrieve a collection

client.collections("countries").retrieve();

Retrieve all collections

client.collections().retrieve();

Drop a collection

client.collections("countries").delete();   

Export a collection

client.collections("Countries").documents().export();

Create an API key

ApiKeySchema apiKeySchema = new ApiKeySchema();
List<String> actionValues = new ArrayList<>();
List<String> collectionValues = new ArrayList<>();

actionValues.add("*");
collectionValues.add("*");

apiKeySchema.description("Admin Key").actions(actionValues).collections(collectionValues);

client.keys().create(apiKeySchema);

Create search only API key

ApiKeySchema apiKeySchema = new ApiKeySchema();
List<String> actionValues = new ArrayList<>();
List<String> collectionValues = new ArrayList<>();

actionValues.add("documents:search");
collectionValues.add("countries");

apiKeySchema.description("Search only Key").actions(actionValues).collections(collectionValues);

client.keys().create(apiKeySchema);

Retrieve an API key

client.keys("6").retrieve();

List all the API keys

client.keys().retrieve();

Delete an API keys

client.keys("6").delete();

Create or update an override

SearchOverrideSchema searchOverrideSchema = new SearchOverrideSchema();

List<SearchOverrideInclude> searchOverrideIncludes = new ArrayList<>();
searchOverrideIncludes.add(new SearchOverrideInclude().id("422").position(1));
searchOverrideIncludes.add(new SearchOverrideInclude().id("54").position(2));

List<SearchOverrideExclude> searchOverrideExcludes = new ArrayList<>();
searchOverrideExcludes.add(new SearchOverrideExclude().id("287"));

searchOverrideSchema.rule(new SearchOverrideRule().query("new york").match("exact"))
                    .includes(searchOverrideIncludes)
                    .excludes(searchOverrideExcludes);

client.collections("countries").overrides().upsert("new-york", searchOverrideSchema)

Retrieve an Alias

client.collections("countries").overrides("new-york").retrieve();

List all overrides

client.collections("countries").overrides().retrieve();

Delete an override

client.collections("countries").overrides("new-york").delete();

Upsert an Alias

CollectionAliasSchema collectionAliasSchema = new CollectionAliasSchema();
collectionAliasSchema.collectionName("countries");

client.aliases().upsert("countries2", collectionAliasSchema)

Retrieve an Alias

client.aliases("countries2").retrieve();

List all Aliases

client.aliases().retrieve();

Delete an Alias

client.aliases("countries2").delete();

Upsert a multi-way synonym

SearchSynonymSchema synonym = new SearchSynonymSchema();
synonym.addSynonymsItem("France").addSynonymsItem("Germany").addSynonymsItem("Sweden");

client.collections("countries").synonyms().upsert("country-synonyms",synonym)

Upsert a single-way synonym

SearchSynonymSchema synonym = new SearchSynonymSchema();
synonym.root("europe");
synonym.addSynonymsItem("France").addSynonymsItem("Germany").addSynonymsItem("Sweden");

client.collections("countries").synonyms().upsert("continent-synonyms",synonym)

Retrieve a synonym

client.collections("countries").synonyms("continent-synonyms").retrieve();

Retrieve all synonyms

client.collections("countries").synonyms().retrieve();

Delete a synonym

client.collections("countries").synonyms("continent-synonyms").delete();

Create snapshot (for backups)

Map<String, String> query = new HashMap<>();
query.put("snapshot_path","/tmp/typesense-data-snapshot");

client.operations.perform("snapshot",query);

Re-elect Leader

client.operations.perform("vote");

Check health

client.health.retrieve();

Contributing

Please read CONTRIBUTING.md for details on the process for submitting pull requests to this repository.

License

typesense-java is distributed under the Apache 2 license.

Support

Please open a Github issue or join our Slack Community