Download the PHP package 1biot/fiquela without Composer

FiQueLa — File Query Language

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

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.

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

Installation

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

Quick Start

FQL string — write queries just like SQL:

Fluent API — chain PHP methods:

Core Features

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.

UNION — merge results from multiple sources

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

WITH — named, reusable sub-queries (CTE)

Declare one or more Common Table Expressions before the main SELECT, then reference them by name in FROM, JOIN, or UNION branches. Each CTE is materialised once and shared between references — perfect for self-joins or eliminating repetition across UNION branches.

Forward-chaining is allowed (later CTEs may reference earlier ones); WITH RECURSIVE is not yet supported.

Expression Evaluator

FiQueLa 3.0 evaluates arithmetic, function calls, and nested expressions anywhere — in SELECT, WHERE, HAVING, ORDER BY, and ON conditions.

Aggregation

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

Rich Filtering

Export with INTO

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

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

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

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

HTTP Access Log Parsing

Query Nginx and Apache access logs with standard FQL — filter by status code, group by path, aggregate response times.

Custom log formats via Apache log_format pattern:

Two Query Styles

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

Fetching Results

Ecosystem

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

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

Documentation

Full documentation at docs.fiquela.io

• [x] Operator BETWEEN: Add operator BETWEEN for filtering data and add support for dates and ranges.
• [x] XLS/XLSX: Add Excel file support.
• [x] Custom cast type: Add support for custom cast type for SELECT clause.
• [x] Add explain method: Add method explain() for explaining query execution from actual query debugger and provide more complex information about query.
• [x] PHPStan 8: Fix all PHPStan 8 errors.
• [x] Tests: Increase test coverage (80%+).
• [x] Optimize GROUP BY: Optimize GROUP BY for more memory efficient data processing.
• [x] 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.~~
• [x] Documentation: Create detailed guides and examples for advanced use cases. - docs.fiquela.io
• [x] Tests: Increase test coverage (90%+).
• [ ] Next file formats: Add next file formats MessagePack, Parquet, INI and TOML
• [ ] Hashmap cache: Add hashmap cache (Redis, Memcache) for more memory efficient data processing.

Contributing

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