PHPackages                             1biot/fiquela - 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. [File & Storage](/categories/file-storage)
4. /
5. 1biot/fiquela

ActiveLibrary[File & Storage](/categories/file-storage)

1biot/fiquela
=============

FiQueLa - File Query Language - PHP library for querying files

v3.2.2(3w ago)65081MITPHPPHP >=8.2CI passing

Since Dec 19Pushed 3w ago1 watchersCompare

[ Source](https://github.com/1biot/FiQueLa)[ Packagist](https://packagist.org/packages/1biot/fiquela)[ RSS](/packages/1biot-fiquela/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (60)Versions (85)Used By (0)

FiQueLa — File Query Language
=============================

[](#fiquela--file-query-language)

> *\[fi-kju-ela\]* · Query files like a database. No database required.

[![Packagist Version](https://camo.githubusercontent.com/f631ff5a5e2ed7f1403b91600dd667fd44f93764afaeb20570640f7e8a8b6fbc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f3162696f742f66697175656c61)](https://camo.githubusercontent.com/f631ff5a5e2ed7f1403b91600dd667fd44f93764afaeb20570640f7e8a8b6fbc/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f3162696f742f66697175656c61)[![CI](https://github.com/1biot/fiquela/actions/workflows/ci.yml/badge.svg)](https://github.com/1biot/fiquela/actions/workflows/ci.yml)[![Packagist Dependency Version](https://camo.githubusercontent.com/b84036385cbd2ca7dff09e021e66a1f2ea72011e00283d6b2fa7c8dadc91aa2a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f3162696f742f66697175656c612f706870)](https://camo.githubusercontent.com/b84036385cbd2ca7dff09e021e66a1f2ea72011e00283d6b2fa7c8dadc91aa2a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f3162696f742f66697175656c612f706870)[![Packagist License](https://camo.githubusercontent.com/971439eb1f5a14d69e6712636a9bd12891bf6bda5776e8e4376f3335c56820d1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f3162696f742f66697175656c61)](https://camo.githubusercontent.com/971439eb1f5a14d69e6712636a9bd12891bf6bda5776e8e4376f3335c56820d1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f3162696f742f66697175656c61)

[![Coverage](https://camo.githubusercontent.com/9ac93fb9c40434c44e19f655251bdf4c7e53a8a8cd466d4b60b8405753cda93c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d39302e33312532352d6c69676874677265656e)](https://camo.githubusercontent.com/9ac93fb9c40434c44e19f655251bdf4c7e53a8a8cd466d4b60b8405753cda93c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f636f7665726167652d39302e33312532352d6c69676874677265656e)[![PHPUnit Tests](https://camo.githubusercontent.com/33f603bf54ec7aa765bdccf2e7febcfe65c98ca20abfaba0b3f81b3226c824dd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d74657374732533415f313430312d6c69676874677265656e)](https://camo.githubusercontent.com/33f603bf54ec7aa765bdccf2e7febcfe65c98ca20abfaba0b3f81b3226c824dd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f504850556e69742d74657374732533415f313430312d6c69676874677265656e)[![PHPStan](https://camo.githubusercontent.com/66617294b56332dffe4e2475914ac4e87fa608b334da37e8a9792c7a1bc3f5a8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068707374616e2d6c6576656c5f382d6c69676874677265656e)](https://camo.githubusercontent.com/66617294b56332dffe4e2475914ac4e87fa608b334da37e8a9792c7a1bc3f5a8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068707374616e2d6c6576656c5f382d6c69676874677265656e)

**FiQueLa** brings SQL querying to structured files. Filter, join, group, aggregate, and export data from XML, CSV, JSON, NDJSON, YAML, NEON, XLSX, ODS, and HTTP access logs — using familiar SQL syntax or a fluent PHP API.

```
SELECT brand, COUNT(id) AS products, AVG(price) AS avg_price
FROM csv(catalog.csv, delimiter: ";").*
WHERE in_stock = "yes" AND price > 100
GROUP BY brand
HAVING products > 5
ORDER BY avg_price DESC
LIMIT 10
```

---

Why FiQueLa?
------------

[](#why-fiquela)

- **No database setup** — query files directly, just PHP and Composer
- **Familiar SQL** — `SELECT`, `WHERE`, `JOIN`, `GROUP BY`, `HAVING`, `ORDER BY`, `UNION`, `WITH` (CTE), `INTO` and more
- **Cross-format joins** — join a CSV against an XML feed against a JSON file in one query
- **Stream-first** — large files are processed row by row with low memory overhead
- **Expression evaluator** — arithmetic, functions, and nested expressions everywhere

---

Supported Formats
-----------------

[](#supported-formats)

FormatKeyReadWrite (INTO)CSV`csv`✅✅XML`xml`✅✅JSON (stream)`jsonFile`✅✅JSON`json`✅✅NDJSON`ndJson`✅✅XLSX`xls`✅✅ODS`ods`✅✅YAML`yaml`✅—NEON`neon`✅—HTTP access log`log`✅—Directory`dir`✅—---

Installation
------------

[](#installation)

```
composer require 1biot/fiquela
```

Requires PHP 8.2+ with `ext-fileinfo`, `ext-json`, `ext-mbstring`, `ext-xmlreader`, `ext-simplexml`, `ext-libxml` and `ext-iconv`.

---

Quick Start
-----------

[](#quick-start)

**FQL string** — write queries just like SQL:

```
use FQL\Query\Provider;

$results = Provider::fql("
    SELECT name, brand, ROUND(price, 2) AS price
    FROM xml(feed.xml).SHOP.SHOPITEM
    WHERE price > 100 AND in_stock = 'yes'
    ORDER BY price DESC
    LIMIT 20
")->execute()->fetchAll();
```

**Fluent API** — chain PHP methods:

```
use FQL\Enum\Operator;
use FQL\Query\Provider;

$results = Provider::fromFileQuery('xml(feed.xml).SHOP.SHOPITEM')
    ->select('name', 'brand')
    ->round('price', 2)->as('price')
    ->where('price', Operator::GREATER_THAN, 100)
    ->and('in_stock', Operator::EQUAL, 'yes')
    ->orderBy('price')->desc()
    ->limit(20)
    ->execute()
    ->fetchAll();
```

---

Core Features
-------------

[](#core-features)

### Joins — across files and formats

[](#joins--across-files-and-formats)

Join data from different files and formats in a single query. Left, right, inner, full outer, and subquery joins are all supported.

```
SELECT p.name, p.price, c.name AS category
FROM csv(products.csv).* AS p
LEFT JOIN json(categories.json).categories AS c
    ON p.category_id = c.id
WHERE p.price > 500
ORDER BY p.price DESC
```

```
use \FQL\Enum\Operator;
use \FQL\Query\Provider;

$products   = Provider::fromFileQuery('csv(products.csv).*');
$categories = Provider::fromFileQuery('json(categories.json).categories');

$results = $products
    ->select('name', 'price')
    ->select('c.name')->as('category')
    ->leftJoin($categories, 'c')
        ->on('category_id', Operator::EQUAL, 'id')
    ->where('price', Operator::GREATER_THAN, 500)
    ->orderBy('price')->desc()
    ->execute();
```

### UNION — merge results from multiple sources

[](#union--merge-results-from-multiple-sources)

Combine results from different files, formats, or filter conditions. `UNION` deduplicates, `UNION ALL` keeps every row.

```
SELECT id, name, price, "warehouse_a" AS source
FROM csv(warehouse_a.csv).*
WHERE price  1000

-- aggregate expression in HAVING
SELECT brand, SUM(price * qty) AS revenue
FROM csv(items.csv).*
GROUP BY brand
HAVING SUM(price * qty) > 50000
```

### Aggregation

[](#aggregation)

Full `GROUP BY` with aggregate functions, `HAVING` filtering, and `DISTINCT` support.

```
SELECT
    category,
    COUNT(id) AS products,
    SUM(price) AS revenue,
    AVG(price) AS avg_price,
    MIN(price) AS cheapest,
    MAX(price) AS most_expensive,
    GROUP_CONCAT(DISTINCT name, " | ") AS product_list
FROM json(products.json).products
GROUP BY category
HAVING products > 10
ORDER BY revenue DESC
```

### Rich Filtering

[](#rich-filtering)

```
-- type checking
WHERE price IS NUMBER AND tags IS ARRAY AND deleted_at IS NULL

-- pattern matching
WHERE name LIKE "%wireless%" AND sku REGEXP "^[A-Z]{2}-\d{4}$"

-- ranges and lists
WHERE price BETWEEN 100 AND 500
AND status IN ("active", "pending")

-- nested condition groups
WHERE price > 100
  AND (stock > 0 OR featured = true)
  AND (category = "electronics" OR discount > 0.2)
```

### Export with INTO

[](#export-with-into)

Write query results directly to a file. Directories are created automatically; existing files are never silently overwritten.

```
-- filter and export to a different format
SELECT name, price, brand
FROM xml(feed.xml).SHOP.SHOPITEM
WHERE price > 500
ORDER BY price DESC
INTO csv(exports/premium.csv)

-- convert between formats
SELECT * FROM csv(data.csv).* INTO json(data.json).root.items
SELECT * FROM json(data.json).root.items INTO xlsx(data.xlsx).Sheet1.A1
```

Supported output formats: **CSV**, **JSON**, **NDJSON**, **XML**, **XLSX**, **ODS**.

### Functions

[](#functions)

**String:** `CONCAT`, `CONCAT_WS`, `UPPER`, `LOWER`, `SUBSTRING`, `REPLACE`, `LPAD`, `RPAD`, `EXPLODE`, `IMPLODE`, `LOCATE`, `REVERSE`, `MATCH AGAINST`

**Math:** `ROUND`, `CEIL`, `FLOOR`, `MOD`

**Utility:** `IF`, `CASE WHEN`, `COALESCE`, `NULLIF`, `CAST`, `DATE_FORMAT`, `NOW`, `CURDATE`, `RANDOM_STRING`, `BASE64_ENCODE`, `BASE64_DECODE`

**Aggregate:** `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`, `GROUP_CONCAT` — all with optional `DISTINCT`

### EXPLAIN ANALYZE

[](#explain-analyze)

Profile query execution without leaving PHP. Every pipeline phase reports row counts, wall time, and memory usage.

```
EXPLAIN ANALYZE
SELECT brand, COUNT(id) AS products, SUM(price) AS revenue
FROM csv(catalog.csv, delimiter: ";").*
GROUP BY brand
ORDER BY revenue DESC
```

```
| phase  | rows_in | rows_out | time_ms  | duration_pct | mem_peak_kb |
|--------|---------|----------|----------|--------------|-------------|
| stream | null    | 178 362  | 4 230.1  | 61%          | 14 231.5    |
| where  | 178 362 | 95 110   | 1 840.3  | 27%          | 14 231.5    |
| group  | 95 110  | 42       | 810.5    | 12%          | 18 540.2    |
| sort   | 42      | 42       | 2.1      | = 400
GROUP BY path
ORDER BY hits DESC
LIMIT 20
```

Custom log formats via Apache `log_format` pattern:

```
FROM log(access.log, format: "custom", pattern: "%h %t %r %>s %D").*
```

---

Two Query Styles
----------------

[](#two-query-styles)

FiQueLa supports both styles interchangeably — pick whichever fits your workflow.

FQL stringFluent APIFamiliaritySQL developersPHP developersDynamic queriesString interpolationMethod chainingIDE support—Autocomplete, typesReadabilityHigh for complex joinsHigh for simple filters---

Fetching Results
----------------

[](#fetching-results)

```
$results = $query->execute();

// all rows as array
$rows = $results->fetchAll();

// first row only
$row = $results->fetch();

// single scalar value
$value = $results->fetchSingle('price');

// map to DTO
$dtos = $results->fetchAll(ProductDTO::class);

// stream row by row (low memory)
foreach ($results->getIterator() as $row) {
    // process $row
}
```

---

Ecosystem
---------

[](#ecosystem)

ProjectDescription[**FiQueLa CLI**](https://github.com/1biot/fiquela-cli)Interactive REPL and command-line querying with paginated table output[**FiQueLa API**](https://github.com/1biot/fiquela-api)RESTful server with JWT auth, file management, query history, and export[**FiQueLa Studio**](https://studio.fiquela.io)Web-based visual query explorer — connect to any FiQueLa API instance```
# Install CLI
curl -fsSL https://raw.githubusercontent.com/1biot/fiquela-cli/main/install.sh | bash

# Interactive REPL
fiquela-cli --file=data.csv

# Single query
fiquela-cli "SELECT name, price FROM csv(data.csv).* WHERE price > 100;"
```

[![Deploy to DigitalOcean](https://camo.githubusercontent.com/1959f5da42c67ccef3538861164e5d4bb24c70a9920a996eedb4ce5c4c2a3946/68747470733a2f2f7777772e6465706c6f79746f646f2e636f6d2f646f2d62746e2d626c75652e737667)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/1biot/fiquela-api/tree/main?refcode=92025543cb9f)

---

Known Limitations
-----------------

[](#known-limitations)

- `JOIN` and `ORDER BY` load data into memory — plan accordingly for very large datasets
- `INTO` throws `FileAlreadyExistsException` if the target file already exists

---

Roadmap
-------

[](#roadmap)

- MessagePack format support
- Parquet format support
- Redis / APCu hashmap cache for JOIN
- LSP server for `.fql` files (PhpStorm, VS Code)

---

Documentation
-------------

[](#documentation)

Full documentation at **[docs.fiquela.io](https://docs.fiquela.io)**

- **Operator BETWEEN**: Add operator `BETWEEN` for filtering data and add support for dates and ranges.
- **XLS/XLSX**: Add Excel file support.
- **Custom cast type**: Add support for custom cast type for `SELECT` clause.
- **Add explain method**: Add method `explain()` for explaining query execution from actual query debugger and provide more complex information about query.
- **PHPStan 8**: Fix all PHPStan 8 errors.
- **Tests**: Increase test coverage (80%+).
- **Optimize GROUP BY**: Optimize `GROUP BY` for more memory efficient data processing.
- **DELETE, UPDATE, INSERT**: Support for manipulating data in files. - Instead of this, it will comes support for exporting data to files (CSV, NDJson, MessagePack, and more...) by `INTO` clause.
- **Documentation**: Create detailed guides and examples for advanced use cases. - [docs.fiquela.io](https://docs.fiquela.io)
- **Tests**: Increase test coverage (90%+).
- **Next file formats**: Add next file formats [MessagePack](https://msgpack.org/), [Parquet](https://parquet.apache.org/docs/file-format/), [INI](https://en.wikipedia.org/wiki/INI_file) and [TOML](https://toml.io/en/)
- **Hashmap cache**: Add hashmap cache (Redis, Memcache) for more memory efficient data processing.

---

Contributing
------------

[](#contributing)

Contributions are welcome! Fork the repo, create a branch, make your changes, and open a pull request. All tests must pass.

```
composer install
composer test       # PHP CodeSniffer, PHPStan level 8, PHPUnit
composer examples   # run example queries
```

###  Health Score

51

—

FairBetter than 95% of packages

Maintenance95

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 90.2% 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 ~9 days

Total

60

Last Release

24d ago

Major Versions

v1.5.0 → v2.0.0-beta2025-01-28

v2.12.0 → v3.0.02026-04-24

PHP version history (2 changes)v1.0.0PHP >=8.1

v2.4.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/13da3fbfa40eb5a98e777311648bb526c4e38e50b9bc6abaeccb55ae2fea2d02?d=identicon)[1biot](/maintainers/1biot)

---

Top Contributors

[![lebeda](https://avatars.githubusercontent.com/u/1889394?v=4)](https://github.com/lebeda "lebeda (231 commits)")[![1biot](https://avatars.githubusercontent.com/u/61222114?v=4)](https://github.com/1biot "1biot (24 commits)")[![iammartinbelobrad](https://avatars.githubusercontent.com/u/212016?v=4)](https://github.com/iammartinbelobrad "iammartinbelobrad (1 commits)")

---

Tags

aggregation-functionscsv-parserdata-queryingdata-transformationjson-streamndjson-parserneon-parserphpquery-buildersql-syntaxstructured-datastructured-filesxls-readerxml-readeryaml-parser

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/1biot-fiquela/health.svg)

```
[![Health](https://phpackages.com/badges/1biot-fiquela/health.svg)](https://phpackages.com/packages/1biot-fiquela)
```

###  Alternatives

[kimai/kimai

Kimai - Time Tracking

4.8k9.0k1](/packages/kimai-kimai)[craftcms/cms

Craft CMS

3.6k3.6M3.1k](/packages/craftcms-cms)[pimcore/pimcore

Content & Product Management Framework (CMS/PIM/E-Commerce)

3.8k3.8M508](/packages/pimcore-pimcore)[statamic/cms

The Statamic CMS Core Package

4.8k3.6M987](/packages/statamic-cms)[silverstripe/framework

The SilverStripe framework

7313.7M2.8k](/packages/silverstripe-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)

PHPackages © 2026

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