Weave Code
Elasticsearch Query Builder Laravel Package
spatie/elasticsearch-query-builder
A lightweight, fluent PHP API for building and executing ElasticSearch queries. Chain queries and aggregations, then call search(). Built for Spatie's search-string-parser but flexible enough to cover most common use cases.
Build and execute an Elasticsearch search query using a fluent PHP API
Frequently asked questions about Elasticsearch Query Builder
- How do I install spatie/elasticsearch-query-builder in a Laravel app?
- Run composer require spatie/elasticsearch-query-builder. It ships as a plain Composer dependency with no Laravel auto-discovery, so after installing you still need to bind Elastic\Elasticsearch\Client in a service provider and inject it into Spatie\ElasticsearchQueryBuilder\Builder. Check the package's composer.json for PHP and elasticsearch/elasticsearch version constraints before installing.
- Does spatie/elasticsearch-query-builder work with Laravel 10, 11, or 12?
- There is no Laravel-specific version constraint because the package is framework agnostic and does not register a service provider. It works with any Laravel version that satisfies its PHP requirement and the underlying elasticsearch/elasticsearch client constraint. In practice, check composer.json for the PHP and ES client requirements rather than looking for a Laravel support matrix.
- Which Elasticsearch versions does spatie/elasticsearch-query-builder support?
- The package major tracks the official client major: use v1 with elasticsearch/elasticsearch v7 and the current release line with elasticsearch/elasticsearch v8. Elasticsearch 9 support is unverified, so a cluster or SDK upgrade should be treated as a coupled change requiring a package upgrade and testing. There is no independent rollback path between the cluster version and the query builder version.
- Is spatie/elasticsearch-query-builder a Laravel package with a service provider?
- No. It is a thin, stateless query-construction layer with no service provider, facade, publishable config, or index and mapping lifecycle management. You own the Laravel integration: a config/elasticsearch.php for hosts, credentials, timeouts and index prefixes, a singleton binding for Elastic\Elasticsearch\Client, and a factory or repository that injects the client into Builder.
- How do I execute a search and get results with this query builder?
- Instantiate Spatie\ElasticsearchQueryBuilder\Builder with an Elastic\Elasticsearch\Client, call index(), add queries and aggregations, then call search(). The search() method executes through the official client and returns the client response. If you need to inspect or transport the request yourself, call getPayload() to get the Elasticsearch DSL array instead.
- What query types and aggregations can I build with spatie/elasticsearch-query-builder?
- The README documents bool, term and terms, match, phrase, multi-match, range, nested with inner hits, wildcard, regexp, geo_shape, percolate, and ids queries, plus a comparable set of aggregations. It also supports sorting, field selection, pagination, collapse, and a MultiBuilder for multi-search. The package was built to serve spatie/elasticsearch-search-string-parser, so treat missing query shapes as expected rather than defects.
- Can I use raw Elasticsearch DSL with spatie/elasticsearch-query-builder?
- Yes. getPayload() is the escape hatch: compose any DSL fragment manually and still route it through the same builder and client. You keep connection handling and execution consistent, but you lose the fluent API for that part of the query. This is useful for new or uncommon Elasticsearch features the package has not wrapped yet.
- Should I use spatie/elasticsearch-query-builder instead of Laravel Scout?
- Choose based on whether search is a product differentiator or a commodity lookup. Laravel Scout plus an Elasticsearch driver is the cheaper, more conventional path for simple model search and is backed by a larger ecosystem. This package gives you direct control over the Elasticsearch DSL, which is worth the ownership cost when you need custom queries, aggregations, or a search-string parser. They can coexist, but avoid duplicating the same search path in both.
- How do I test code that uses spatie/elasticsearch-query-builder?
- Because the builder is stateless and getPayload() returns a plain array, you can unit test the generated DSL without a running cluster. Mock or stub Elastic\Elasticsearch\Client when asserting that search() is called, and keep integration tests against a real or containerized Elasticsearch for query semantics, scoring, and aggregations. That split keeps fast tests fast while still validating behavior that only the cluster can confirm.
- Is spatie/elasticsearch-query-builder actively maintained and production ready?
- It is a Spatie package with a README, changelog, tagged releases, and CI, so maintenance hygiene is good. Ecosystem validation is thin, however: roughly 181 stars and zero dependents means few public downstream users to learn from, and you would be an early-ish adopter. There is no community to absorb edge cases, so budget time for owning uncovered query shapes and for testing upgrades against your cluster.
Weaver
How can I help you explore Laravel packages today?