Typesense Java Client ☕ 🔍

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

Note: This package is still under development. Some existing APIs might change or new APIs might be available in the future.

Installation

Download the JAR file from the releases section of this repository and add it to your project.

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

Usage

Create a new client

ArrayList<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>");

Clienr client = new Client(configuration);

Create a new collection

ArrayList<Field> fields = new ArrayList<>();
fields.add(new Field().name("countryName").type("string"));
fields.add(new Field().name("capital").type("string"));
fields.add(new Field().name("gdp").type("int32").facet(true));

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

client.collections().create(collectionSchema);

Index a document

HashMap<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

HashMap<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")
                                        .addQueryByItem("countryName").addQueryByItem("capital")
                                        .addPrefixItem(true).addPrefixItem(false);
SearchResult searchResult = client.collections("countries").documents().search(searchParameters);

Update a document

HashMap<String, Object> hmap = new HashMap<>();
hmap.put("gdp", 8);
client.collections("countries").documents("28").retrieve(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)

HashMap<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