PHPackages                             entreya/csvquery - 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. [Database & ORM](/categories/database)
4. /
5. entreya/csvquery

ActiveLibrary[Database & ORM](/categories/database)

entreya/csvquery
================

High-performance CSV query engine with Go-powered indexing and Yii2-like fluent API

v1.0.0(3mo ago)00MITGoPHP >=8.1CI passing

Since Feb 7Pushed 2mo agoCompare

[ Source](https://github.com/entreya/csvquery)[ Packagist](https://packagist.org/packages/entreya/csvquery)[ Docs](https://github.com/entreya/csvquery)[ RSS](/packages/entreya-csvquery/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

CsvQuery
========

[](#csvquery)

 **Query massive CSV files like a database — powered by a Go sidecar engine.**

 [![Build Status](https://camo.githubusercontent.com/7e9140200940173beb939a07d19a9e20bbafff840111177380425ccd0dd39296/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f656e74726579612f63737671756572792f6275696c642e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265)](https://github.com/entreya/csvquery/actions) [![Version](https://camo.githubusercontent.com/ea9ef426d7257249967444fc38f23d854e483b614a19030e12feb17fa0bb5ff5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e302e302d626c75653f7374796c653d666c61742d737175617265)](https://github.com/entreya/csvquery/releases) [![License](https://camo.githubusercontent.com/422db9fd40f5831c765cf6530b6750c081b696bd18d904cf89554df98c676277/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e3f7374796c653d666c61742d737175617265)](LICENSE) [![Go](https://camo.githubusercontent.com/3661074559d3055c9ad54b59276d9cad318d773432a6558291ebaa3c692346d7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f676f2d312e32312b2d3030414444383f7374796c653d666c61742d737175617265266c6f676f3d676f266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/3661074559d3055c9ad54b59276d9cad318d773432a6558291ebaa3c692346d7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f676f2d312e32312b2d3030414444383f7374796c653d666c61742d737175617265266c6f676f3d676f266c6f676f436f6c6f723d7768697465) [![PHP](https://camo.githubusercontent.com/f5e70b01f8ddc0bd6e79b47f482e96cfa5a18071de8751ce3c4ddab7b1b3e30c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312b2d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://camo.githubusercontent.com/f5e70b01f8ddc0bd6e79b47f482e96cfa5a18071de8751ce3c4ddab7b1b3e30c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d382e312b2d3737374242343f7374796c653d666c61742d737175617265266c6f676f3d706870266c6f676f436f6c6f723d7768697465)

**CsvQuery** is a high-performance query engine that turns CSV files (10 GB–1 TB+) into searchable, indexed data stores. A fluent PHP API (inspired by Yii2 ActiveQuery) communicates with a Go sidecar daemon over Unix Domain Sockets, delivering **sub-millisecond query latency** without the overhead of a traditional database.

> 📚 **Full documentation →** [entreya.github.io/csvquery-docs](https://entreya.github.io/csvquery-docs/)

---

Table of Contents
-----------------

[](#table-of-contents)

- [Key Features](#-key-features)
- [Architecture](#-architecture)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Usage Examples](#-usage-examples)
- [API Reference](#-api-reference)
- [Data Flow](#-data-flow)
- [Performance](#-performance)
- [CLI Reference](#-cli-reference)
- [Project Structure](#-project-structure)
- [Testing](#-testing)
- [Contributing](#-contributing)
- [License & Acknowledgments](#-license--acknowledgments)

---

✨ Key Features
--------------

[](#-key-features)

FeatureDescription🚀 **SIMD-Accelerated Parsing**AVX2 / SSE4.2 instructions scan CSV delimiters at hardware speed (10 GB/s+)📊 **Massive Scale**Benchmarked on 18 M+ rows, 10 GB+ files💾 **Memory Efficient**`mmap`-based file access with LZ4-compressed indexes🔍 **Yii2-like Fluent API**Familiar `find()→where()→all()` query builder for PHP developers⚡ **Zero-IO Index Scans**`COUNT(*)` operations resolve from index metadata alone — the CSV is never opened🔄 **Live Updates**Sidecar `_updates.json` system makes immutable CSVs mutable🔌 **Daemon Mode**Persistent Go process over UDS for ~1 ms latency (vs ~200 ms per-process spawn)🌐 **Cross-Platform**Pre-compiled binaries for Linux, macOS, and Windows (AMD64 & ARM64)---

🏗️ Architecture
---------------

[](#️-architecture)

CsvQuery uses a **PHP + Go Sidecar** design. Your PHP application talks to a long-lived Go daemon through **Unix Domain Sockets (UDS)**, keeping query latency under a millisecond.

 ```
graph TB
    subgraph "PHP Application Layer"
        A["Your PHP App"] --> B["CsvQuery"]
        B --> C["ActiveQuery"]
        C --> D["GoBridge"]
        D --> E["SocketClient"]
    end

    subgraph "Go Sidecar Engine"
        E  F["UDS Daemon"]
        F --> G["Query Engine"]
        G --> H["Index Reader"]
        G --> I["SIMD Scanner"]
        H --> J["LZ4 Decompressor"]
    end

    subgraph "Disk Storage"
        K[("Raw CSV File")]
        L[(".cidx Indexes")]
        M[(".bloom Filters")]
        N[("_updates.json")]
    end

    G -.- K
    H -.- L
    G -.- M
    G -.- N
```

      Loading ### Key Technologies

[](#key-technologies)

ComponentTechnologyWhy**Parsing**AVX2 / SSE4.2 SIMDScan delimiters at hardware speed**Compression**LZ4 block codec10× faster decompression than Gzip**File Access**`mmap`Zero-copy reads, OS-managed page cache**IPC**Unix Domain Sockets~1 ms round-trip vs ~200 ms process spawn**Probabilistic Filter**Bloom filtersReject non-matching index blocks before decompression### Design Patterns

[](#design-patterns)

PatternWherePurpose**Sidecar Process**Go daemonOffload CPU-intensive work from PHP**Fluent Builder**`ActiveQuery`Chainable, composable query construction**Singleton**`SocketClient`Reuse a single daemon connection per request**Generator / Streaming**`each()`, `GoBridge::query()`Process millions of rows without loading them all into memory**External Merge Sort**IndexerBuild indexes on files larger than available RAM---

📦 Installation
--------------

[](#-installation)

### Prerequisites

[](#prerequisites)

RequirementVersionPHP8.1+Composer2.xGo *(optional — pre-compiled binaries included)*1.21+### Via Composer

[](#via-composer)

```
composer require entreya/csvquery
```

The Go binary is **compiled automatically** on `composer install`. If Go is not available on your machine, the bundled pre-compiled binary for your platform will be used instead.

### Build Commands

[](#build-commands)

```
composer build          # Build for current platform
composer build:all      # Cross-compile for all platforms
composer build:clean    # Remove all compiled binaries
```

### Manual Build

[](#manual-build)

```
php scripts/build.php           # Current OS/arch
php scripts/build.php --all     # All platforms
```

### Platform Notes

[](#platform-notes)

PlatformNotes**macOS**ARM64 (Apple Silicon) and AMD64 binaries included**Linux**AMD64 and ARM64 binaries included**Windows**Statically linked `.exe` — no MinGW / Cygwin / WSL required> See [CONTRIBUTING.md](CONTRIBUTING.md) for per-platform development setup.

---

🚀 Quick Start
-------------

[](#-quick-start)

```