PHPackages                             kiwiz/esquery - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. kiwiz/esquery

ActiveLibrary[API Development](/categories/api)

kiwiz/esquery
=============

Elasticsearch querying library

v1.0.1(7y ago)202.7k9[1 PRs](https://github.com/kiwiz/esquery/pulls)MITPHPCI passing

Since Sep 23Pushed 7y ago5 watchersCompare

[ Source](https://github.com/kiwiz/esquery)[ Packagist](https://packagist.org/packages/kiwiz/esquery)[ Docs](https://github.com/kiwiz/esquery)[ RSS](/packages/kiwiz-esquery/feed)WikiDiscussions master Synced 4w ago

READMEChangelogDependencies (3)Versions (6)Used By (0)

ESQuery
=======

[](#esquery)

ESQuery is a query parser for querying Elasticsearch. Each ESQuery query consists of one or more "commands", separated by the pipe (`|`) character. During execution, each command is translated into an Elasticsearch DSL query and sent to the server. Any results that are returned get passed off to the next command in the chain.

Structure
---------

[](#structure)

Each query is structured as follows:

```
    Options* SearchCommand ('|' [AggCommand | JoinCommand])* ('|' [TransactionCommand])?

```

In English:

- A series of 0 or more options
- A SearchCommand
- A series of 0 or more AggCommands or JoinCommands
- An optional TransactionCommand

with each command separated from the next by a pipe (`|`) character.

Syntax
------

[](#syntax)

### Options

[](#options)

Options that can be enabled/disabled within each query. Each option is prefixed by a `$`.

`sort`

- A list of fields to sort on.
- Type: List
- Example: `$sort:[time:ASC, type:DESC, duration:DESC]`

`map`

- A mapping of fields and what to rename them to.
- Type: Map
- Example: `$map:[request_ip:ip, geoip_location:loc]`

#### Options

[](#options-1)

- `date_field`: The name of the field used as the timestamp.
- `to`: The latest date to pull results from. (Unix timestamp)
- `from`: The earliest date to pull results from. (Unix timestamp)
- `size`: The maximum number of results to return.
- `flatten`: Flatten any nested structures into a flat key-value map.
- `fields`: The list of fields to return.

### Commands

[](#commands)

#### Search

[](#search)

A standard Lucene QueryParser [query](http://lucene.apache.org/core/5_4_1/queryparser/org/apache/lucene/queryparser/classic/package-summary.html). Almost all of the features are available in ESQuery. The ones that aren't primarily relate to scoring, and are listed here:

- Fuzzy searches
- Proximity searches
- Boosting a term

Must always be the first command.

- Syntax: `QUERY_PARSER_QUERY`
- Example: `level:99 type:normal`

##### Lists

[](#lists)

Inserts an array of values into a query. ESQuery runs a terms filter on the values that are provided.

- Syntax: `KEY:@LIST_NAME`
- Example: `src_ip:@bad_ip_list`

#### Join

[](#join)

Extracts the values from the previous command and makes them available to the following query.

- Syntax: `'join' 'source:'SOURCE_FIELD 'target:'DEST_FIELD QUERY_PARSER_QUERY`
- Example: `type:tcp | join source:src_ip target:dst_ip flags:0`

#### Transaction

[](#transaction)

Combines documents with matching values for a given field. Must always be the final command (if used).

- Syntax: `'trans' 'field:'FIELD_NAME`
- Example: `trans field:request_uuid`

### Aggregation

[](#aggregation)

Standard Elasticsearch aggregations. Multiple aggregations can be chained to nest them. ESQuery will return the bucketed data in a table. Any parameters that an aggregation takes can be passed in after setting the field.

Supported aggs: `terms`, `sig_terms`, `card`, `max`, `avg`, `sum`

- Syntax: `'agg:'AGG_TYPE 'field:'FIELD_NAME (AGG_OPT':'AGG_OPT_VAL)*`
- Example: `agg:terms field:user_id min_doc_count:50`

Examples
--------

[](#examples)

Match all documents.

```
*

```

Get a count of requests to `abc.com` bucketed by `ip_addr`.

```
host:abc.com | agg:terms field:ip_addr

```

Find all requests to `abc.com` sorted by `ip_addr` and `date`.

```
$sort:[ip_addr:ASC, date:ASC] host:abc.com

```

Find all users with the same email as `bob`.

```
user:bob | join source:email target:email

```

Find and group all log lines associated with requests that came from `10.0.0.5`.

```
ip_addr:10.0.0.5 | trans field:request_uuid

```

Find any documents that have a value from `@include` but not a value from `@exclude`.

```
tag:@include -tag:@exclude

```

Find the most common useragent.

```
* | agg:terms field:user_agent size:1

```

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity29

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~259 days

Total

4

Last Release

2791d ago

Major Versions

v0.9.1 → v1.0.02018-11-08

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/3122114?v=4)[Kai](/maintainers/kiwiz)[@kiwiz](https://github.com/kiwiz)

---

Top Contributors

[![kiwiz](https://avatars.githubusercontent.com/u/3122114?v=4)](https://github.com/kiwiz "kiwiz (25 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/kiwiz-esquery/health.svg)

```
[![Health](https://phpackages.com/badges/kiwiz-esquery/health.svg)](https://phpackages.com/packages/kiwiz-esquery)
```

###  Alternatives

[wheelpros/fitment-platform-api

Magento 2 (Open Source)

12.1k1.2k](/packages/wheelpros-fitment-platform-api)[unopim/unopim

UnoPim Laravel PIM

10.5k2.2k](/packages/unopim-unopim)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

84735.1k](/packages/flow-php-flow)[shift31/laravel-elasticsearch

A Laravel Service Provider for the Elasticsearch API client

193370.7k1](/packages/shift31-laravel-elasticsearch)[handcraftedinthealps/elasticsearch-dsl

Elasticsearch DSL library

212.7M19](/packages/handcraftedinthealps-elasticsearch-dsl)[m6web/elasticsearch-bundle

Symfony2 Bundle on top of elasticsearch/elasticsearch-php

22635.7k2](/packages/m6web-elasticsearch-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)