// dependencies { // implementation("com.turbopuffer:turbopuffer-java:+") // implementation("com.openai:openai-java:+") // } package com.turbopuffer.docs; import com.openai.client.okhttp.*; import com.openai.errors.*; import com.openai.models.embeddings.*; import com.turbopuffer.client.okhttp.*; import com.turbopuffer.models.namespaces.*; import java.util.*; public class QuickStart { public static void main(String[] args) { var tpuf = TurbopufferOkHttpClient.builder() .fromEnv() // API tokens are created in the dashboard: https://turbopuffer.com/dashboard .apiKey(System.getenv("TURBOPUFFER_API_KEY")) // Pick the right region: https://turbopuffer.com/docs/regions .region("gcp-us-central1") .build(); var ns = tpuf.namespace("quickstart-example-java"); // Upsert documents with vectors and attributes ns.write( NamespaceWriteParams.builder() .addUpsertRow( Row.builder() .put("id", 1) .put("vector", openAiOrRandVector("walrus narwhal")) .put("category", "mammal") .put("public", 1) .put("text", "walrus narwhal") .build() ) .addUpsertRow( Row.builder() .put("id", 2) .put("vector", openAiOrRandVector("pufferfish clownfish swordfish")) .put("category", "fish") .put("public", 0) .put("text", "pufferfish clownfish swordfish") .build() ) .distanceMetric(DistanceMetric.COSINE_DISTANCE) .schema( Schema.builder() .put( "text", AttributeSchemaConfig.builder() .type("string") // More schema & FTS options // https://turbopuffer.com/docs/write#schema .fullTextSearch(FullTextSearchConfig.defaults()) .build() ) .build() ) .build() ); // Query nearest neighbors with filter var queryResult = ns.query( NamespaceQueryParams.builder() .rankBy(RankBy.ann("vector", openAiOrRandVector("arctic sea mammal"))) .limit(10) .filters(Filter.and(Filter.eq("category", "mammal"), Filter.eq("public", 1))) .includeAttributes("category") .build() ); System.out.println(queryResult); // NamespaceQueryResponse{rows=[{$dist=0.42773545, id=1, category=mammal}]} // Full-text search on an attribute // To combine FTS and vector search concurrently and fuse results, see https://turbopuffer.com/docs/hybrid-search var ftsResult = ns.query( NamespaceQueryParams.builder() .limit(10) .filters(Filter.eq("category", "mammal")) .rankBy(RankByText.bm25("text", "quick walrus")) .build() ); System.out.println(ftsResult); // NamespaceQueryResponse{rows=[{$dist=0.7549128, id=1}]} // Vectors can be updated by passing new data for an existing ID ns.write( NamespaceWriteParams.builder() .addUpsertRow( Row.builder() .put("id", 1) .put("vector", openAiOrRandVector("foo")) .put("name", "foo") .put("public", 1) .build() ) .addUpsertRow( Row.builder() .put("id", 2) .put("vector", openAiOrRandVector("foo")) .put("name", "foo") .put("public", 1) .build() ) .addUpsertRow( Row.builder() .put("id", 3) .put("vector", openAiOrRandVector("foo")) .put("name", "foo") .put("public", 1) .build() ) .distanceMetric(DistanceMetric.COSINE_DISTANCE) .build() ); // Vectors are deleted by ID. ns.write(NamespaceWriteParams.builder().addDelete(1).addDelete(3).build()); } // Create an embedding with OpenAI, could be {Cohere, Voyage, Mixed Bread, ...} // Requires OPENAI_API_KEY to be set (https://platform.openai.com/settings/organization/api-keys) public static List<Float> openAiOrRandVector(String text) { if (System.getenv("OPENAI_API_KEY") == null) { System.out.println("OPENAI_API_KEY not set, using random vectors"); return randVector(); } var client = OpenAIOkHttpClient.fromEnv(); try { var params = EmbeddingCreateParams.builder() .input(text) .model(EmbeddingModel.TEXT_EMBEDDING_3_SMALL) .build(); var response = client.embeddings().create(params); return response.data().get(0).embedding(); } catch (OpenAIException e) { System.out.println("OpenAI error, using random vectors: " + e.getMessage()); return randVector(); } } public static List<Float> randVector() { Random rand = new Random(); List<Float> vector = new java.util.ArrayList<>(2); vector.add(rand.nextFloat()); vector.add(rand.nextFloat()); return vector; } }

Quickstart Guide