TurbopufferEngine
class TurbopufferEngine extends Engine implements DeletesByFilter, SupportsSemanticSearch
Turbopuffer search engine implementation.
Provides full-text, semantic, and hybrid search using Turbopuffer as the backend.
Properties
| protected EngineOperationRunner|null | $operationRunner | The operation runner assigned to this engine. |
from Engine |
| protected string | $operationRunnerEngineName | The configured name of this engine. |
from Engine |
Methods
Pluck and return the primary keys of the given results.
Get the total count from a raw result returned by the engine.
Create a search index.
Delete a search index.
Get the import concurrency allowed for the given model.
Assign the operation runner to this engine.
Run a Builder operation through the operation runner.
Pluck and return the primary keys of the given results using the given key name.
Create a new Turbopuffer engine instance.
Add embeddings to the given searchable records.
Run a namespace request, treating a missing namespace as empty.
Build Turbopuffer search parameters for the query.
Build a hybrid full-text and semantic query.
Get the validated BM25 weights of the model's searchable attributes.
Combine native and Scout filters.
Normalize a filter value.
Ensure the Scout key is returned for model hydration.
Validate embedding configuration shared by indexing and querying.
Determine if Turbopuffer should generate embeddings natively.
Validate a native embedding schema and return its vector attribute.
Generate and validate embeddings using the optional Hypervel AI SDK.
Details
at line 53
void
update(Collection $models)
Update the given models in the search index.
at line 192
void
delete(Collection $models)
Remove the given models from the search index.
at line 249
mixed
search(Builder $builder)
Perform a search against the engine.
at line 260
mixed
paginate(Builder $builder, int $perPage, int $page)
Perform a paginated search against the engine.
at line 671
Collection
mapIds(mixed $results)
Pluck and return the primary keys of the given results.
at line 679
Collection
map(Builder $builder, mixed $results, Model $model)
Map the given results to instances of the given model.
at line 712
LazyCollection
lazyMap(Builder $builder, mixed $results, Model $model)
Map the given results to instances of the given model via a lazy collection.
at line 744
int
getTotalCount(mixed $results)
Get the total count from a raw result returned by the engine.
at line 752
void
flush(Model $model)
Flush all of the model's records from the engine.
at line 763
mixed
createIndex(string $name, array $options = [])
Create a search index.
at line 774
mixed
deleteIndex(string $name)
Delete a search index.
in
Engine at line 98
int
importConcurrency(Model $model, int $configured)
Get the import concurrency allowed for the given model.
in
Engine at line 111
Engine
setOperationRunner(EngineOperationRunner $runner, string $engineName)
Assign the operation runner to this engine.
The runner persists on a cached engine for the worker lifetime. Engines without observable operations retain no runner.
in
Engine at line 127
protected bool
hasObservableOperations()
Determine if this engine has operations worth observing.
in
Engine at line 137
void
runUpdate(Collection $models)
Update the given models through the operation runner.
in
Engine at line 167
void
runDelete(Collection $models)
Delete the given models through the operation runner.
in
Engine at line 215
mixed
runPaginate(Builder $builder, int $perPage, int $page)
Paginate through the operation runner.
in
Engine at line 235
void
runFlush(Model $model)
Flush the given model through the operation runner.
in
Engine at line 265
mixed
runOperation(string $operation, Builder $builder, Closure $callback, string|null $index = null)
Run a Builder operation through the operation runner.
An omitted index uses the Builder's configured or searchable index. Pass an explicit index when the operation targets another dataset.
in
Engine at line 291
Collection
mapIdsFrom(mixed $results, string $key)
Pluck and return the primary keys of the given results using the given key name.
in
Engine at line 299
Collection
keys(Builder $builder)
Get the results of the query as a Collection of primary keys.
in
Engine at line 307
Collection
get(Builder $builder)
Get the results of the given query mapped onto models.
in
Engine at line 319
LazyCollection
cursor(Builder $builder)
Get a lazy collection for the given query mapped onto models.
at line 41
__construct(TurbopufferClient $turbopuffer, array $config = [], bool $softDelete = false)
Create a new Turbopuffer engine instance.
at line 145
protected array
addEmbeddingsToRecords(array $records, array $settings)
Add embeddings to the given searchable records.
at line 215
void
deleteByFilter(Builder $builder)
Delete every document matching the prepared Builder filters.
at line 303
protected array|null
countFilters(Builder $builder)
Get the filters that count a paginated search's matches.
Full-text rankings exclude documents without a query token, so the count matches any token in the weighted searchable attributes as BM25 does.
at line 333
protected array
performSearch(Builder $builder, int $limit)
Perform a search against Turbopuffer.
at line 365
protected mixed
ignoringMissingNamespace(Closure $callback, mixed $missing = null)
Run a namespace request, treating a missing namespace as empty.
Turbopuffer creates namespaces on their first write and reports a 404 for namespaces that were never written or have been flushed.
at line 383
array
buildSearchParameters(Builder $builder, int $limit)
Build Turbopuffer search parameters for the query.
at line 424
protected array
buildHybridSearchParameters(Builder $builder, int $limit)
Build a hybrid full-text and semantic query.
at line 470
protected array
rankBy(Builder $builder)
Build the ranking expression for the query.
at line 502
protected array
fullTextRankBy(Builder $builder)
Build the full-text ranking expression for a query.
at line 524
protected array
searchableAttributeWeights(Builder $builder)
Get the validated BM25 weights of the model's searchable attributes.
at line 552
protected array
semanticRankBy(Builder $builder)
Build the semantic ranking expression for a query.
at line 570
protected array|null
filters(Builder $builder)
Build filters for the query.
at line 617
protected array|null
combineFilters(array|null $nativeFilters, array|null $scoutFilters)
Combine native and Scout filters.
at line 633
protected mixed
filterValue(mixed $value)
Normalize a filter value.
at line 644
protected array
ensureIdIsReturned(array $parameters)
Ensure the Scout key is returned for model hydration.
at line 663
protected string
field(Builder $builder, string $field)
Resolve a Scout field name to a Turbopuffer field name.
at line 784
protected array
modelSettings(Model $model)
Get the configured settings for a model.
at line 794
protected array
embeddingSettings(Model $model)
Get the validated embedding settings for a model.
at line 825
protected array
validateEmbeddingSettings(array $settings)
Validate embedding configuration shared by indexing and querying.
at line 859
protected bool
usesNativeEmbeddings(array $settings)
Determine if Turbopuffer should generate embeddings natively.
at line 867
protected string
validateNativeEmbeddingSchema(string $attribute, mixed $embed)
Validate a native embedding schema and return its vector attribute.
at line 895
protected array
generateEmbeddings(array $inputs, array $settings)
Generate and validate embeddings using the optional Hypervel AI SDK.
at line 918
protected TurbopufferNamespace
namespace(Builder $builder)
Get the Turbopuffer namespace for a search.
at line 928
protected bool
usesSoftDelete(Model $model)
Determine if the given model uses soft deletes.