https://github.com/typesense/typesense-java
Java client for Typesense
https://github.com/typesense/typesense-java
http-client java search search-engine typesense
Last synced: 6 months ago
JSON representation
Java client for Typesense
- Host: GitHub
- URL: https://github.com/typesense/typesense-java
- Owner: typesense
- License: apache-2.0
- Created: 2021-04-23T17:39:38.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-02-18T16:05:17.000Z (8 months ago)
- Last Synced: 2025-03-31T14:09:17.297Z (6 months ago)
- Topics: http-client, java, search, search-engine, typesense
- Language: Java
- Homepage: https://typesense.org/docs/latest/api/
- Size: 476 KB
- Stars: 64
- Watchers: 5
- Forks: 32
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Typesense Java Client ☕ 🔍
Java client library for accessing the HTTP API of [Typesense](https://typesense.org) search engine.
## Installation
The client is available on Maven central:
```groovy
dependencies {
implementation 'org.typesense:typesense-java:1.3.0'
}
```
```xml
org.typesense
typesense-java
1.3.0
```
```java
import org.typesense.api.*;
import org.typesense.model.*;
import org.typesense.resources.*;
```
## Usage
### Create a new client
```java
List 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),"");
Client client = new Client(configuration);
```
### Create a new collection
```java
List 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
```java
String schemaJson = new String(
Files.readAllBytes(Paths.get("schema.json")),
StandardCharsets.UTF_8
);
client.collections().create(schemaJson);
```
### Index a document
```java
Map hmap = new HashMap<>();
hmap.put("countryName","India");
hmap.put("capital","Delhi");
hmap.put("gdp", 10);
client.collections("Countries").documents().create(hmap);
```
### Upserting a document
```java
Map 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
```java
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
```java
SearchParameters searchParameters = new SearchParameters()
.q("tokoyo")
.queryBy("countryName,capital")
.prefix("true,false");
SearchResult searchResult = client.collections("Countries").documents().search(searchParameters);
```
### Update a document
```java
Map hmap = new HashMap<>();
hmap.put("gdp", 8);
client.collections("Countries").documents("28").update(hmap);
```
### Retrieve a document
```java
client.collections("Countries").documents("28").retrieve();
```
### Delete a document
```java
client.collections("Countries").documents("28").delete();
```
### Delete documents using query
```java
DeleteDocumentsParameters deleteDocumentsParameters = new DeleteDocumentsParameters();
deleteDocumentsParameters.filterBy("gdp:=[2,8]");
deleteDocumentsParameters.batchSize(10);
```
### Retrieve a collection
```java
client.collections("Countries").retrieve();
```
### Retrieve all collections
```java
client.collections().retrieve();
```
### Drop a collection
```java
client.collections("Countries").delete();
```
### Export a collection
```java
client.collections("Countries").documents().export();
```
### Create an analytics rule
```java
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
```java
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
```java
AnalyticsRulesRetrieveSchema rules = client.analytics().rules().retrieve();
```
### Retrieve a single analytics rule
```java
AnalyticsRuleSchema rule = client.analytics().rules("failed-searches").retrieve();
```
### Delete an analytics rule
```java
client.analytics().rules("failed-searches").delete();
```
#### Create an analytics event
```java
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
```java
List 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
```java
StopwordsSetRetrieveSchema set = client.stopwords("common-words").retrieve();
```
### Retrieve all stopwords sets
```java
StopwordsSetsRetrieveAllSchema sets = client.stopwords().retrieve();
```
### Delete a stopwords set
```java
client.stopwords("common-words").delete();
```
### Create an API key
```java
ApiKeySchema apiKeySchema = new ApiKeySchema();
List actionValues = new ArrayList<>();
List collectionValues = new ArrayList<>();
actionValues.add("*");
collectionValues.add("*");
apiKeySchema.description("Admin Key").actions(actionValues).collections(collectionValues);
client.keys().create(apiKeySchema);
```
### Create search only API key
```java
ApiKeySchema apiKeySchema = new ApiKeySchema();
List actionValues = new ArrayList<>();
List 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
```java
client.keys("6").retrieve();
```
### List all the API keys
```java
client.keys().retrieve();
```
### Delete an API keys
```java
client.keys("6").delete();
```
### Create or update an override
```java
SearchOverrideSchema searchOverrideSchema = new SearchOverrideSchema();
List searchOverrideIncludes = new ArrayList<>();
searchOverrideIncludes.add(new SearchOverrideInclude().id("422").position(1));
searchOverrideIncludes.add(new SearchOverrideInclude().id("54").position(2));
List 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
```java
client.collections("Countries").overrides("new-york").retrieve();
```
### List all overrides
```java
client.collections("Countries").overrides().retrieve();
```
### Delete an override
```java
client.collections("Countries").overrides("new-york").delete();
```
### Upsert an Alias
```java
CollectionAliasSchema collectionAliasSchema = new CollectionAliasSchema();
collectionAliasSchema.collectionName("Countries");
client.aliases().upsert("countries2", collectionAliasSchema)
```
### Retrieve an Alias
```java
client.aliases("countries2").retrieve();
```
### List all Aliases
```java
client.aliases().retrieve();
```
### Delete an Alias
```java
client.aliases("countries2").delete();
```
### Upsert a multi-way synonym
```java
SearchSynonymSchema synonym = new SearchSynonymSchema();
synonym.addSynonymsItem("France").addSynonymsItem("Germany").addSynonymsItem("Sweden");
client.collections("Countries").synonyms().upsert("country-synonyms",synonym)
```
### Upsert a single-way synonym
```java
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
```java
client.collections("Countries").synonyms("continent-synonyms").retrieve();
```
### Retrieve all synonyms
```java
client.collections("Countries").synonyms().retrieve();
```
### Delete a synonym
```java
client.collections("Countries").synonyms("continent-synonyms").delete();
```
### Create snapshot (for backups)
```java
Map query = new HashMap<>();
query.put("snapshot_path","/tmp/typesense-data-snapshot");
client.operations.perform("snapshot",query);
```
### Re-elect Leader
```java
client.operations.perform("vote");
```
### Check health
```java
client.health.retrieve();
```
## Contributing
Please read [CONTRIBUTING.md](https://github.com/typesense/typesense-java/blob/master/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](https://join.slack.com/t/typesense-community/shared_invite/zt-mx4nbsbn-AuOL89O7iBtvkz136egSJg)