Skip to content

typesense/typesense-java

Folders and files

NameName
Last commit message
Last commit date

Latest commit

0571a01 · Feb 3, 2025
Sep 7, 2024
Sep 7, 2024
Apr 26, 2022
Nov 7, 2024
Sep 7, 2024
Dec 15, 2023
Apr 23, 2021
Feb 3, 2025
Feb 3, 2025
Apr 30, 2023
Sep 24, 2024
Sep 22, 2021
Sep 22, 2021
May 13, 2021
Dec 15, 2023

Repository files navigation

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:1.2.0'
}
<dependency>
    <groupId>org.typesense</groupId>
    <artifactId>typesense-java</artifactId>
    <version>1.2.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);

Create a new collection from JSON file

String schemaJson = new String(
    Files.readAllBytes(Paths.get("schema.json")),
    StandardCharsets.UTF_8
);
client.collections().create(schemaJson);

Index a document

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

client.collections("Countries").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("Countries").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 analytics rule

AnalyticsRuleSchema analyticsRule = new AnalyticsRuleSchema();
analyticsRule.setName("popular-queries");
analyticsRule.setType(AnalyticsRuleSchema.TypeEnum.POPULAR_QUERIES);
analyticsRule.setParams(new AnalyticsRuleParameters()
        .source(new AnalyticsRuleParametersSource()
                .collections(Arrays.asList("Countries")))
        .destination(new AnalyticsRuleParametersDestination()
                .collection("top_searches")));

client.analytics().rules().create(analyticsRule);

Upsert an analytics rule

AnalyticsRuleUpsertSchema analyticsRule = new AnalyticsRuleUpsertSchema()
        .type(AnalyticsRuleUpsertSchema.TypeEnum.NOHITS_QUERIES)
        .params(new AnalyticsRuleParameters()
                .source(new AnalyticsRuleParametersSource()
                        .collections(Arrays.asList("Countries")))
                .destination(new AnalyticsRuleParametersDestination()
                        .collection("failed_searches")));

client.analytics().rules().upsert("failed-searches", analyticsRule);

Retrieve all analytics rules

AnalyticsRulesRetrieveSchema rules = client.analytics().rules().retrieve();

Retrieve a single analytics rule

AnalyticsRuleSchema rule = client.analytics().rules("failed-searches").retrieve();

Delete an analytics rule

client.analytics().rules("failed-searches").delete();

Create an analytics event

AnalyticsEventCreateSchema analyticsEvent = new AnalyticsEventCreateSchema()
        .type("conversion")
        .name("purchase_made")
        .data(Map.of(
                "product_id", "123",
                "user_id", "user_456",
                "amount", "99.99"
        ));

client.analytics().events().create(analyticsEvent);

Upsert a stopwords set

List<String> stopwords = new ArrayList<>();
stopwords.add("the");
stopwords.add("of");
stopwords.add("and");

StopwordsSetUpsertSchema stopwordsSet = new StopwordsSetUpsertSchema();
stopwordsSet.stopwords(stopwords);

client.stopwords().upsert("common-words", stopwordsSet);

Retrieve a stopwords set

StopwordsSetRetrieveSchema set = client.stopwords("common-words").retrieve();

Retrieve all stopwords sets

StopwordsSetsRetrieveAllSchema sets = client.stopwords().retrieve();

Delete a stopwords set

client.stopwords("common-words").delete();

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