turbopuffer

https://turbopuffer.com/docs
Admin
turbopuffer is a fast vector and full-text search engine built on top of object storage. It offers...
Tokens:254,560
Snippets:1,587
Trust Score:9.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Full Runnable Example: Turbopuffer Quickstart

Source: https://turbopuffer.com/docs/quickstart

This comprehensive example demonstrates setting up Turbopuffer, generating embeddings with an external model (Fireworks AI Qwen), upserting data, and performing vector search, full-text search, regex filtering, and aggregation. Ensure you have the necessary API keys and packages installed.

```typescript
// $ npm install @turbopuffer/turbopuffer openai
import { Turbopuffer } from "@turbopuffer/turbopuffer";
import OpenAI from "openai";

const tpuf = new Turbopuffer({
  apiKey: process.env.TURBOPUFFER_API_KEY, // created here: https://turbopuffer.com/dashboard
  region: "gcp-us-central1", // choose best region: https://turbopuffer.com/docs/regions
});

const namespace = process.env.TURBOPUFFER_NAMESPACE ?? `quickstart-${Math.random().toString(36).slice(2, 10)}`;
const ns = tpuf.namespace(namespace);
const fireworks = new OpenAI({
  apiKey: process.env.FIREWORKS_API_KEY,
  baseURL: "https://api.fireworks.ai/inference/v1",
});

// Create an embedding with Qwen on Fireworks.
// Requires FIREWORKS_API_KEY to be set (https://fireworks.ai/settings/users/api-keys)
async function embed(text: string): Promise<number[]> {
  return (
    await fireworks.embeddings.create({
      model: "fireworks/qwen3-embedding-8b",
      input: text,
      encoding_format: "float",
    })
  ).data[0].embedding;
}

// Upsert documents with vectors and attributes
await ns.write({
  upsert_rows: [
    {
      id: 1,
      vector: await embed("walrus narwhal"),
      category: ["mammal"],
      public: true,
      text: "walrus narwhal",
    },
    {
      id: 2,
      vector: await embed("pufferfish clownfish swordfish"),
      category: ["fish"],
      public: false,
      text: "pufferfish clownfish swordfish",
    },
  ],
  distance_metric: "cosine_distance",
  schema: {
    text: {
      // Configure FTS/BM25. Other attributes have inferred types (`public`: int).
      type: "string",
      // More schema & FTS options:
      // https://turbopuffer.com/docs/write#schema
      full_text_search: true,
      regex: true,
    },
    category: { type: "[]string", full_text_search: true },
  },
});

// Query nearest neighbors with a filter
let result = await ns.query({
  rank_by: ["vector", "ANN", await embed("arctic sea mammal")],
  limit: 10,
  filters: ["public", "Eq", true],
});
console.log(result.rows);
// [{ '$dist': 0.42773545, id: 1 }]

// Full-text search on an attribute
// To combine FTS and vector search concurrently, see:
// https://turbopuffer.com/docs/hybrid-search
result = await ns.query({
  limit: 10,
  filters: ["public", "Eq", true],
  rank_by: ["Sum", [
    ["Product", 2, ["category", "BM25", "mammal"]],
    ["text", "BM25", "quick walrus"],
  ]],
});
console.log(result.rows);
// [{ '$dist': 0.7549128, id: 1 }]

// Regex filter — matches "pufferfish", "swordfish", "clownfish"
result = await ns.query({
  limit: 10,
  filters: ["text", "Regex", "\\w+fish"],
});
console.log(result.rows);

// Count documents grouped by category
const groupedResult = await ns.query({
  aggregate_by: { count_by_category: ["Count"] },
  group_by: ["category"],
});
console.log(groupedResult.aggregation_groups);
// [
//   { category: ["fish"], count_by_category: 1 },
//   { category: ["mammal"], count_by_category: 1 },
// ]

```

--------------------------------

### Java Turbopuffer Quickstart Example

Source: https://turbopuffer.com/docs/quickstart

This snippet demonstrates initializing the Turbopuffer client, writing documents with vectors and attributes, querying nearest neighbors with filters, and performing full-text search. It includes setup for API keys and region selection.

```java
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;
  }
}

```

--------------------------------

### Go Quickstart Example

Source: https://turbopuffer.com/docs/quickstart

This comprehensive example demonstrates how to use the Turbopuffer Go client to upsert documents with vectors and attributes, perform nearest neighbor searches with filters, conduct full-text searches, and group results by category. It requires setting TURBOPUFFER_API_KEY and VOYAGE_API_KEY environment variables.

```go
// $ go get github.com/turbopuffer/turbopuffer-go/v2 github.com/openai/openai-go
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	"github.com/openai/openai-go"
	openaioption "github.com/openai/openai-go/option"
	"github.com/turbopuffer/turbopuffer-go/v2"
	tpufoption "github.com/turbopuffer/turbopuffer-go/v2/option"
	"github.com/turbopuffer/turbopuffer-go/v2/packages/param"
)

// Create an embedding with Voyage.
// Requires VOYAGE_API_KEY to be set:
// https://dashboard.voyageai.com/organization/api-keys
func embed(ctx context.Context, text string) []float32 {
	client := openai.NewClient(
		openaioption.WithAPIKey(os.Getenv("VOYAGE_API_KEY")),
		openaioption.WithBaseURL("https://api.voyageai.com/v1"),
	)
	resp, err := client.Embeddings.New(ctx, openai.EmbeddingNewParams{
		Input: openai.EmbeddingNewParamsInputUnion{OfString: openai.String(text)},
		Model: openai.EmbeddingModel("voyage-4-lite"),
	})
	if err != nil {
		panic(err)
	}
	return toFloat32Slice(resp.Data[0].Embedding)
}

func toFloat32Slice(values []float64) []float32 {
	out := make([]float32, len(values))
	for i, value := range values {
		out[i] = float32(value)
	}
	return out
}

func main() {
	ctx := context.Background()
	tpuf := turbopuffer.NewClient(
		tpufoption.WithAPIKey(os.Getenv("TURBOPUFFER_API_KEY")), // created here: https://turbopuffer.com/dashboard
		tpufoption.WithRegion("gcp-us-central1"), // choose best region: https://turbopuffer.com/docs/regions
	)

	namespace := os.Getenv("TURBOPUFFER_NAMESPACE")
	if namespace == "" {
		namespace = fmt.Sprintf("quickstart-%d", time.Now().UnixNano())
	}
	ns := tpuf.Namespace(namespace)

	// Upsert documents with vectors and attributes
	_, err := ns.Write(
		ctx,
		turbopuffer.NamespaceWriteParams{
			UpsertRows: []turbopuffer.RowParam{
				{
					"id":       1,
					"vector":   embed(ctx, "walrus narwhal"),
					"category": []string{"mammal"},
					"public":   true,
					"text":     "walrus narwhal",
				},
				{
					"id":       2,
					"vector":   embed(ctx, "pufferfish clownfish swordfish"),
					"category": []string{"fish"},
					"public":   false,
					"text":     "pufferfish clownfish swordfish",
				},
			},
			DistanceMetric: turbopuffer.DistanceMetricCosineDistance,
			Schema: map[string]turbopuffer.AttributeSchemaConfigParam{
				"text": {
					Type:           "string",
					FullTextSearch: &turbopuffer.FullTextSearchConfigParam{},
					Regex:          param.NewOpt(true),
				},
				"category": {
					Type:           "[]string",
					FullTextSearch: &turbopuffer.FullTextSearchConfigParam{},
				},
			},
		},
	)
	if err != nil {
		panic(err)
	}

	// Query nearest neighbors with a filter
	res, err := ns.Query(
		ctx,
		turbopuffer.NamespaceQueryParams{
			RankBy: turbopuffer.NewRankByAnn("vector", embed(ctx, "arctic sea mammal")),
			Limit: turbopuffer.LimitParam{
				Total: 10,
			},
			Filters: turbopuffer.NewFilterEq("public", true),
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Print(turbopuffer.PrettyPrint(res.Rows))
	// [{"id": 1, "vector": null, "$dist": 0.42773545}]

	// Full-text search on an attribute
	// To combine FTS and vector search concurrently, see:
	// https://turbopuffer.com/docs/hybrid-search
	res, err = ns.Query(
		ctx,
		turbopuffer.NamespaceQueryParams{
			Limit: turbopuffer.LimitParam{
				Total: 10,
			},
			Filters: turbopuffer.NewFilterEq("public", true),
			RankBy: turbopuffer.NewRankByTextSum([]turbopuffer.RankByText{
				turbopuffer.NewRankByTextProduct(2, turbopuffer.NewRankByTextBM25("category", "mammal")),
				turbopuffer.NewRankByTextBM25("text", "quick walrus"),
			}),
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Print(turbopuffer.PrettyPrint(res.Rows))
	// [{"id": 1, "vector": null, "$dist": 0.7549128}]

	// Regex filter — matches "pufferfish", "swordfish", "clownfish"
	res, err = ns.Query(
		ctx,
		turbopuffer.NamespaceQueryParams{
			Limit:   turbopuffer.LimitParam{Total: 10},
			Filters: turbopuffer.NewFilterRegex("text", `\w+fish`),
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Print(turbopuffer.PrettyPrint(res.Rows))

	// Count documents grouped by category
	groupedResult, err := ns.Query(
		ctx,
		turbopuffer.NamespaceQueryParams{
			AggregateBy: map[string]turbopuffer.AggregateBy{
				"count_by_category": turbopuffer.NewAggregateByCount(),
			},
			GroupBy: []turbopuffer.GroupBy{turbopuffer.NewGroupByAttr("category")},
		},
	)
	if err != nil {
		panic(err)
	}
	fmt.Println(turbopuffer.PrettyPrint(groupedResult.AggregationGroups))
	// [
	//   { category: ["fish"], count_by_category: 1 },
	//   { category: ["mammal"], count_by_category: 1 },
	// ]
}

```

--------------------------------

### Java Quickstart Example

Source: https://turbopuffer.com/docs/quickstart

This example demonstrates how to initialize the Turbopuffer client, upsert documents with vectors and attributes, perform nearest neighbor searches with filters, conduct full-text searches, apply regex filters, and group results by category. It requires setting TURBOPUFFER_API_KEY and GEMINI_API_KEY environment variables.

```java
// Gradle: implementation("com.turbopuffer:turbopuffer-java:+"), implementation("com.google.genai:google-genai:+")
package com.turbopuffer.docs;

import com.google.genai.Client;
import com.google.genai.types.EmbedContentConfig;
import com.turbopuffer.client.okhttp.*;
import com.turbopuffer.models.namespaces.*;
import java.util.*;

class QuickStartGemini {

  public static void main(String[] args) {
    var tpuf = TurbopufferOkHttpClient.builder()
      .fromEnv()
      .apiKey(System.getenv("TURBOPUFFER_API_KEY")) // created here: https://turbopuffer.com/dashboard
      .region("gcp-us-central1") // choose best region: https://turbopuffer.com/docs/regions
      .build();

    var namespace = Optional.ofNullable(System.getenv("TURBOPUFFER_NAMESPACE")).orElse(
      "quickstart-" + UUID.randomUUID().toString().substring(0, 8)
    );
    var ns = tpuf.namespace(namespace);

    // Upsert documents with vectors and attributes
    ns.write(
      NamespaceWriteParams.builder()
        .addUpsertRow(
          Row.builder()
            .put("id", 1)
            .put("vector", embed("walrus narwhal"))
            .put("category", List.of("mammal"))
            .put("public", true)
            .put("text", "walrus narwhal")
            .build()
        )
        .addUpsertRow(
          Row.builder()
            .put("id", 2)
            .put("vector", embed("pufferfish clownfish swordfish"))
            .put("category", List.of("fish"))
            .put("public", false)
            .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())
                .regex(true)
                .build()
            )
            .put(
              "category",
              AttributeSchemaConfig.builder()
                .type("[]string")
                .fullTextSearch(FullTextSearchConfig.defaults())
                .build()
            )
            .build()
        )
        .build()
    );

    // Query nearest neighbors with a filter
    var queryResult = ns.query(
      NamespaceQueryParams.builder()
        .rankBy(RankBy.vector("vector", embed("arctic sea mammal")))
        .limit(10)
        .filters(Filter.eq("public", true))
        .build()
    );
    System.out.println(queryResult);
    // NamespaceQueryResponse{rows=[{$dist=0.42773545, id=1}]}

    // Full-text search on an attribute
    // To combine FTS and vector search concurrently, see:
    // https://turbopuffer.com/docs/hybrid-search
    var ftsResult = ns.query(
      NamespaceQueryParams.builder()
        .limit(10)
        .filters(Filter.eq("public", true))
        .rankBy(
          RankByText.sum(
            RankByText.product(2, RankByText.bm25("category", "mammal")),
            RankByText.bm25("text", "quick walrus")
          )
        )
        .build()
    );
    System.out.println(ftsResult);
    // NamespaceQueryResponse{rows=[{$dist=0.7549128, id=1}]}

    // Regex filter — matches "pufferfish", "swordfish", "clownfish"
    var regexResult = ns.query(
      NamespaceQueryParams.builder().limit(10).filters(Filter.regex("text", "\\w+fish")).build()
    );
    System.out.println(regexResult);

    // Count documents grouped by category
    var groupedResult = ns.query(
      NamespaceQueryParams.builder()
        .aggregateBy(Map.of("count_by_category", AggregateBy.count("id")))
        .groupBy(List.of("category"))
        .build()
    );
    System.out.println(groupedResult.aggregationGroups().get());
    // [{category=[fish], count_by_category=1}, {category=[mammal], count_by_category=1}]
  }

  // Create an embedding with Gemini.
  // Requires GEMINI_API_KEY to be set (https://aistudio.google.com/app/apikey)
  public static List<Float> embed(String text) {
    try (Client client = Client.builder().apiKey(System.getenv("GEMINI_API_KEY")).build()) {
      return client.models
        .embedContent(
          "gemini-embedding-001",
          text,
          EmbedContentConfig.builder().taskType("RETRIEVAL_DOCUMENT").build()
        )
        .embeddings()
        .orElseThrow()
        .get(0)
        .values()
        .orElseThrow();
    }
  }
}

```

--------------------------------

### Java Quickstart Example for Turbopuffer and Cohere

Source: https://turbopuffer.com/docs/quickstart

This example demonstrates how to set up the Turbopuffer client, upsert documents with vectors and attributes, perform nearest neighbor searches with filters, and execute full-text searches. It requires TURBOPUFFER_API_KEY and COHERE_API_KEY environment variables.

```java
// Gradle: implementation("com.turbopuffer:turbopuffer-java:+"), implementation("com.cohere:cohere-java:+")
package com.turbopuffer.docs;

import com.cohere.api.Cohere;
import com.cohere.api.resources.v2.requests.V2EmbedRequest;
import com.cohere.api.types.EmbedInputType;
import com.turbopuffer.client.okhttp.*;
import com.turbopuffer.models.namespaces.*;
import java.util.*;

class QuickStartCohere {

  public static void main(String[] args) {
    var tpuf = TurbopufferOkHttpClient.builder()
      .fromEnv()
      .apiKey(System.getenv("TURBOPUFFER_API_KEY")) // created here: https://turbopuffer.com/dashboard
      .region("gcp-us-central1") // choose best region: https://turbopuffer.com/docs/regions
      .build();

    var namespace = Optional.ofNullable(System.getenv("TURBOPUFFER_NAMESPACE")).orElse(
      "quickstart-" + UUID.randomUUID().toString().substring(0, 8)
    );
    var ns = tpuf.namespace(namespace);

    // Upsert documents with vectors and attributes
    ns.write(
      NamespaceWriteParams.builder()
        .addUpsertRow(
          Row.builder()
            .put("id", 1)
            .put("vector", embed("walrus narwhal"))
            .put("category", List.of("mammal"))
            .put("public", true)
            .put("text", "walrus narwhal")
            .build()
        )
        .addUpsertRow(
          Row.builder()
            .put("id", 2)
            .put("vector", embed("pufferfish clownfish swordfish"))
            .put("category", List.of("fish"))
            .put("public", false)
            .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())
                .regex(true)
                .build()
            )
            .put(
              "category",
              AttributeSchemaConfig.builder()
                .type("[]string")
                .fullTextSearch(FullTextSearchConfig.defaults())
                .build()
            )
            .build()
        )
        .build()
    );

    // Query nearest neighbors with a filter
    var queryResult = ns.query(
      NamespaceQueryParams.builder()
        .rankBy(RankBy.vector("vector", embed("arctic sea mammal")))
        .limit(10)
        .filters(Filter.eq("public", true))
        .build()
    );
    System.out.println(queryResult);
    // NamespaceQueryResponse{rows=[{$dist=0.42773545, id=1}]}

    // Full-text search on an attribute
    // To combine FTS and vector search concurrently, see:
    // https://turbopuffer.com/docs/hybrid-search
    var ftsResult = ns.query(
      NamespaceQueryParams.builder()
        .limit(10)
        .filters(Filter.eq("public", true))
        .rankBy(
          RankByText.sum(
            RankByText.product(2, RankByText.bm25("category", "mammal")),
            RankByText.bm25("text", "quick walrus")
          )
        )
        .build()
    );
    System.out.println(ftsResult);
    // NamespaceQueryResponse{rows=[{$dist=0.7549128, id=1}]}

    // Regex filter — matches "pufferfish", "swordfish", "clownfish"
    var regexResult = ns.query(
      NamespaceQueryParams.builder().limit(10).filters(Filter.regex("text", "\\w+fish")).build()
    );
    System.out.println(regexResult);

    // Count documents grouped by category
    var groupedResult = ns.query(
      NamespaceQueryParams.builder()
        .aggregateBy(Map.of("count_by_category", AggregateBy.count("id")))
        .groupBy(List.of("category"))
        .build()
    );
    System.out.println(groupedResult.aggregationGroups().get());
    // [{category=[fish], count_by_category=1}, {category=[mammal], count_by_category=1}]
  }

  // Create an embedding with Cohere.
  // Requires COHERE_API_KEY to be set (https://dashboard.cohere.com/api-keys)
  public static List<Float> embed(String text) {
    var response = Cohere.builder()
      .token(System.getenv("COHERE_API_KEY"))
      .clientName("turbopuffer-quickstart")
      .build()
      .v2()
      .embed(
        V2EmbedRequest.builder()
          .model("embed-v4.0")
          .inputType(EmbedInputType.SEARCH_DOCUMENT)
          .texts(List.of(text))
          .build()
      );
    return response
      .getEmbeddings()
      .getFloat()
      .orElseThrow()
      .get(0)
      .stream()
      .map(Double::floatValue)
      .toList();
  }
}
```

--------------------------------

### Ruby Test Setup and Query Example

Source: https://turbopuffer.com/docs/testing

This Ruby snippet shows how to set up a test namespace, write data, and query using Minitest. It includes setup and teardown methods for managing the test namespace.

```ruby
# tpuf_test.rb

# Run with `ruby tpuf_test.rb`.

require "minitest/autorun"
require "securerandom"
require "turbopuffer"

class TestTpuf < Minitest::Test
  # Create a namespace for each test
  def setup
    tpuf = Turbopuffer::Client.new(
      region: "gcp-us-central1", # choose best region: https://turbopuffer.com/docs/regions
    )
    @ns = tpuf.namespace("test-" + SecureRandom.alphanumeric(32))
  end

  # Always delete the namespace after the test
  def teardown
    @ns.delete_all
  rescue Turbopuffer::Errors::NotFoundError
    # If the namespace never got created, no cleanup is needed.
  end

  def test_query
    @ns.write(
      upsert_rows: [
        { id: 1, vector: [1, 1] },
        { id: 2, vector: [2, 2] },
      ],
      distance_metric: Turbopuffer::DistanceMetric::COSINE_DISTANCE,
    )
    res = @ns.query(rank_by: ["vector", "ANN", [1.1, 1.1]], limit: 10)
    assert_equal(res.rows.first.id, 1)
  end
end

```

--------------------------------

### Full Runnable Example: Turbopuffer and Cohere Integration

Source: https://turbopuffer.com/docs/quickstart

This snippet demonstrates a complete workflow from setup to querying. It requires installing `@turbopuffer/turbopuffer` and `cohere-ai`, and setting environment variables for API keys.

```typescript
// $ npm install @turbopuffer/turbopuffer cohere-ai
import { Turbopuffer } from "@turbopuffer/turbopuffer";
import { CohereClient } from "cohere-ai";

const tpuf = new Turbopuffer({
  apiKey: process.env.TURBOPUFFER_API_KEY, // created here: https://turbopuffer.com/dashboard
  region: "gcp-us-central1", // choose best region: https://turbopuffer.com/docs/regions
});

const namespace = process.env.TURBOPUFFER_NAMESPACE ?? `quickstart-${Math.random().toString(36).slice(2, 10)}`;
const ns = tpuf.namespace(namespace);
const cohere = new CohereClient({ token: process.env.COHERE_API_KEY });

// Create an embedding with Cohere.
// Requires COHERE_API_KEY to be set (https://dashboard.cohere.com/api-keys)
async function embed(text: string): Promise<number[]> {
  return (await cohere.v2.embed({
    model: "embed-v4.0",
    inputType: "search_document",
    texts: [text],
    embeddingTypes: ["float"],
  })).embeddings.float![0];
}

// Upsert documents with vectors and attributes
await ns.write({
  upsert_rows: [
    {
      id: 1,
      vector: await embed("walrus narwhal"),
      category: ["mammal"],
      public: true,
      text: "walrus narwhal",
    },
    {
      id: 2,
      vector: await embed("pufferfish clownfish swordfish"),
      category: ["fish"],
      public: false,
      text: "pufferfish clownfish swordfish",
    },
  ],
  distance_metric: "cosine_distance",
  schema: {
    text: {
      // Configure FTS/BM25. Other attributes have inferred types (`public`: int).
      type: "string",
      // More schema & FTS options:
      // https://turbopuffer.com/docs/write#schema
      full_text_search: true,
      regex: true,
    },
    category: { type: "[]string", full_text_search: true },
  },
});

// Query nearest neighbors with a filter
let result = await ns.query({
  rank_by: ["vector", "ANN", await embed("arctic sea mammal")],
  limit: 10,
  filters: ["public", "Eq", true],
});
console.log(result.rows);
// [{ '$dist': 0.42773545, id: 1 }]

// Full-text search on an attribute
// To combine FTS and vector search concurrently, see:
// https://turbopuffer.com/docs/hybrid-search
result = await ns.query({
  limit: 10,
  filters: ["public", "Eq", true],
  rank_by: ["Sum", [
    ["Product", 2, ["category", "BM25", "mammal"]],
    ["text", "BM25", "quick walrus"],
  ]],
});
console.log(result.rows);
// [{ '$dist': 0.7549128, id: 1 }]

// Regex filter — matches "pufferfish", "swordfish", "clownfish"
result = await ns.query({
  limit: 10,
  filters: ["text", "Regex", "\\w+fish"],
});
console.log(result.rows);

// Count documents grouped by category
const groupedResult = await ns.query({
  aggregate_by: { count_by_category: ["Count"] },
  group_by: ["category"],
});
console.log(groupedResult.aggregation_groups);
// [
//   { category: ["fish"], count_by_category: 1 },
//   { category: ["mammal"], count_by_category: 1 },
// ]

```

--------------------------------

### Turbopuffer C# Quickstart Example

Source: https://turbopuffer.com/docs/quickstart

This C# code demonstrates how to use the Turbopuffer client to interact with a vector database. It covers initializing the client, creating a namespace, upserting documents with vectors and attributes, querying for nearest neighbors with filters, performing full-text search, updating existing vectors, and deleting documents. Ensure you have the Turbopuffer and OpenAI NuGet packages installed and necessary API keys configured.

```csharp
// dotnet add package Turbopuffer
// dotnet add package OpenAI
using System;
using System.Collections.Generic;
using System.Linq;
using OpenAI.Embeddings;
using Turbopuffer;
using Turbopuffer.Models.Namespaces;

using var tpuf = new TurbopufferClient
{
    // API tokens are created in the dashboard: https://turbopuffer.com/dashboard
    // Loaded from TURBOPUFFER_API_KEY env var by default. Override if necessary:
    // ApiKey = "...",

    // Pick the right region: https://turbopuffer.com/docs/regions
    Region = "gcp-us-central1",
};

var ns = tpuf.Namespace("quickstart-example-csharp");

// Upsert documents with vectors and attributes
await ns.Write(
    new NamespaceWriteParams
    {
        UpsertRows =
        [
            new Row()
                .Set("id", 1)
                .Set("vector", OpenAiOrRandVector("walrus narwhal"))
                .Set("category", "mammal")
                .Set("public", 1)
                .Set("text", "walrus narwhal"),
            new Row()
                .Set("id", 2)
                .Set("vector", OpenAiOrRandVector("pufferfish clownfish swordfish"))
                .Set("category", "fish")
                .Set("public", 0)
                .Set("text", "pufferfish clownfish swordfish"),
        ],
        DistanceMetric = DistanceMetric.CosineDistance,
        Schema = new Dictionary<string, AttributeSchemaConfig>
        {
            ["text"] = new AttributeSchemaConfig
            {
                Type = "string",
                // More schema & FTS options
                // https://turbopuffer.com/docs/write#schema
                FullTextSearch = true,
            },
        },
    }
);

// Query nearest neighbors with filter
var queryResult = await ns.Query(
    new NamespaceQueryParams
    {
        RankBy = RankBy.Ann("vector", OpenAiOrRandVector("arctic sea mammal")),
        Limit = 10,
        Filters = Filter.And(Filter.Eq("category", "mammal"), Filter.Eq("public", 1)),
        IncludeAttributes = new List<string> { "category" },
    }
);
foreach (var row in queryResult.GetRows())
{
    Console.WriteLine(row);
}
// {"$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 = await ns.Query(
    new NamespaceQueryParams
    {
        Limit = 10,
        Filters = Filter.Eq("category", "mammal"),
        RankBy = RankByText.BM25("text", "quick walrus"),
    }
);
foreach (var row in ftsResult.GetRows())
{
    Console.WriteLine(row);
}
// {"$dist": 0.7549128, "id": 1}

// Vectors can be updated by passing new data for an existing ID
await ns.Write(
    new NamespaceWriteParams
    {
        UpsertRows =
        [
            new Row().Set("id", 1).Set("vector", OpenAiOrRandVector("foo")).Set("name", "foo").Set("public", 1),
            new Row().Set("id", 2).Set("vector", OpenAiOrRandVector("foo")).Set("name", "foo").Set("public", 1),
            new Row().Set("id", 3).Set("vector", OpenAiOrRandVector("foo")).Set("name", "foo").Set("public", 1),
        ],
        DistanceMetric = DistanceMetric.CosineDistance,
    }
);

// Vectors are deleted by ID.
await ns.Write(new NamespaceWriteParams { Deletes = [1L, 3L] });

// 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)
static List<float> OpenAiOrRandVector(string text)
{
    if (Environment.GetEnvironmentVariable("OPENAI_API_KEY") == null)
    {
        Console.WriteLine("OPENAI_API_KEY not set, using random vectors");
        return RandVector();
    }
    try
    {
        var client = new EmbeddingClient(
            "text-embedding-3-small",
            Environment.GetEnvironmentVariable("OPENAI_API_KEY")
        );
        return [.. client.GenerateEmbedding(text).Value.ToFloats().Span];
    }
    catch (Exception e)
    {
        Console.WriteLine($"OpenAI error, using random vectors: {e.Message}");
        return RandVector();
    }
}

static List<float> RandVector()
{
    return new List<float> { (float)Random.Shared.NextDouble(), (float)Random.Shared.NextDouble() };
}

```

--------------------------------

### C# Test Setup and Query Example

Source: https://turbopuffer.com/docs/testing

This C# snippet demonstrates how to set up a test namespace, write data, and perform a query using xUnit. It includes necessary imports and setup/teardown logic for the test namespace.

```csharp
// TpufTest.cs

// dotnet add package Turbopuffer
// dotnet add package xunit
//
// Run with `dotnet test`.
using System;
using System.Threading.Tasks;
using Turbopuffer;
using Turbopuffer.Exceptions;
using Turbopuffer.Models.Namespaces;
using Turbopuffer.Services;
using Xunit;

public class TpufTest : IAsyncLifetime
{
    private readonly TurbopufferClient _tpuf = new() 
    {
        // Pick the right region: https://turbopuffer.com/docs/regions
        Region = "gcp-us-central1",
    };

    private INamespaceService _ns = null!;

    // Create a namespace for each test, and always delete it afterwards.
    public Task InitializeAsync()
    {
        _ns = _tpuf.Namespace($"test-{Guid.NewGuid():N}");
        return Task.CompletedTask;
    }

    public async Task DisposeAsync()
    {
        try
        {
            await _ns.DeleteAll(new NamespaceDeleteAllParams());
        }
        catch (TurbopufferNotFoundException)
        {
            // If the namespace never got created, no cleanup is needed.
        }
        _tpuf.Dispose();
    }

    [Fact]
    public async Task TestQuery()
    {
        await _ns.Write(
            new NamespaceWriteParams
            {
                UpsertRows =
                [
                    new Row().Set("id", 1).Set("vector", new[] { 1.0f, 1.0f }),
                    new Row().Set("id", 2).Set("vector", new[] { 2.0f, 2.0f }),
                ],
                DistanceMetric = DistanceMetric.CosineDistance,
            }
        );

        var result = await _ns.Query(
            new NamespaceQueryParams
            {
                RankBy = RankBy.Ann("vector", new[] { 1.1f, 1.1f }),
                Limit = 10,
            }
        );
        var rows = result.GetRows();

        Assert.Equal(2, rows.Count);
        Assert.Equal(1, rows[0].Get<int>("id"));
    }
}

```

--------------------------------

### Full Runnable Example with Turbopuffer and Gemini

Source: https://turbopuffer.com/docs/quickstart

This comprehensive example demonstrates setting up Turbopuffer, embedding text using Gemini, upserting documents, and performing vector and full-text searches. Ensure you have the necessary API keys and packages installed.

```typescript
// $ npm install @turbopuffer/turbopuffer @google/genai
import { Turbopuffer } from "@turbopuffer/turbopuffer";
import { GoogleGenAI } from "@google/genai";

const tpuf = new Turbopuffer({
  apiKey: process.env.TURBOPUFFER_API_KEY, // created here: https://turbopuffer.com/dashboard
  region: "gcp-us-central1", // choose best region: https://turbopuffer.com/docs/regions
});

const namespace = process.env.TURBOPUFFER_NAMESPACE ?? `quickstart-${Math.random().toString(36).slice(2, 10)}`;
const ns = tpuf.namespace(namespace);
const gemini = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Create an embedding with Gemini.
// Requires GEMINI_API_KEY to be set (https://aistudio.google.com/app/apikey)
async function embed(text: string): Promise<number[]> {
  return (
    await gemini.models.embedContent({
      model: "gemini-embedding-001",
      contents: text,
      config: { taskType: "RETRIEVAL_DOCUMENT" },
    })
  ).embeddings![0].values!;
}

// Upsert documents with vectors and attributes
await ns.write({
  upsert_rows: [
    {
      id: 1,
      vector: await embed("walrus narwhal"),
      category: ["mammal"],
      public: true,
      text: "walrus narwhal",
    },
    {
      id: 2,
      vector: await embed("pufferfish clownfish swordfish"),
      category: ["fish"],
      public: false,
      text: "pufferfish clownfish swordfish",
    },
  ],
  distance_metric: "cosine_distance",
  schema: {
    text: {
      // Configure FTS/BM25. Other attributes have inferred types (`public`: int).
      type: "string",
      // More schema & FTS options:
      // https://turbopuffer.com/docs/write#schema
      full_text_search: true,
      regex: true,
    },
    category: { type: "[]string", full_text_search: true },
  },
});

// Query nearest neighbors with a filter
let result = await ns.query({
  rank_by: ["vector", "ANN", await embed("arctic sea mammal")],
  limit: 10,
  filters: ["public", "Eq", true],
});
console.log(result.rows);
// [{ '$dist': 0.42773545, id: 1 }]

// Full-text search on an attribute
// To combine FTS and vector search concurrently, see:
// https://turbopuffer.com/docs/hybrid-search
result = await ns.query({
  limit: 10,
  filters: ["public", "Eq", true],
  rank_by: ["Sum", [
    ["Product", 2, ["category", "BM25", "mammal"]],
    ["text", "BM25", "quick walrus"],
  ]],
});
console.log(result.rows);
// [{ '$dist': 0.7549128, id: 1 }]

// Regex filter — matches "pufferfish", "swordfish", "clownfish"
result = await ns.query({
  limit: 10,
  filters: ["text", "Regex", "\\w+fish"],
});
console.log(result.rows);

// Count documents grouped by category
const groupedResult = await ns.query({
  aggregate_by: { count_by_category: ["Count"] },
  group_by: ["category"],
});
console.log(groupedResult.aggregation_groups);
// [
//   { category: ["fish"], count_by_category: 1 },
//   { category: ["mammal"], count_by_category: 1 },
// ]
```
Tokens:
Raw