How trendyol/es-query-builder works
Project Type and Purpose
• This is a Go-based library (es-query-builder) for programmatically constructing Elasticsearch DSL queries.
• It is _not_ a standalone server or web application; it provides a fluent, composable API in Go (“es” package) that produces JSON query/aggregation objects to be sent to an Elasticsearch cluster.
File Structure
• es/: the core package. Contains subpackages or files for:
• Queries (bool, term, match, range, etc.)
• Aggregations (avg, sum, terms, nested, multi-terms, etc.)
• Condition builders (if, constant_score)
• Enums (collect-mode, sort orders, script languages, etc.)
• example/: a minimal Go program showing how a consumer uses the library.
• benchmarks/: performance tests comparing this library against vanilla Go maps and other libraries.
• internal/integration-test/: a suite that:
• Spins up an Elasticsearch container
• Defines document models & repositories
• Loads test data
• Runs true end-to-end queries against ES
• .github/ + CI workflows: GitHub Actions for build/test, security checks, releases.
• Makefile, goreleaser.yml: build and release tooling.
• test/assert/: small assertion helpers.
README for Additional Insights
• Confirms the library’s goal: minimal overhead, fluent API to build JSON DSL.
• Shows sample usage (Bool().Must(…).Aggs(…)), emphasizing the fluent-builder pattern.
• Mentions benchmarks and integration tests—key parts of the architecture.
a. Main Components
• Consumer Code (example or any Go application)
• es-query-builder Library (“es” package)
• Query Builder Core
• Aggregations Module
• Conditions Module
• Enums Module
• Benchmarks Suite
• Integration Test Suite
• Docker/Elasticsearch Container
• Model & Repository Layer
• Test Data Provider
• CI/CD Pipelines (GitHub Actions)
b. Relationships & Interactions
• Consumer → calls → es Library → returns → JSON DSL
• Consumer → (via HTTP client) → Elasticsearch Cluster
• Benchmarks & Integration Tests → import → es Library
• Integration Tests → orchestrate → Docker container
• CI Workflows → trigger → build, test, benchmark, release
c. Architectural Patterns & Principles
• Fluent-Builder Pattern: chainable methods producing immutable query structures
• Composite Pattern: query/aggregation nodes forming a tree
• Separation of Concerns: core builder (es/) vs. consumer code vs. test harness
• Internal Packages: hide test-only utilities (in internal/)
d. Key Technologies & Frameworks
• Go Modules (go.mod)
• Docker (for integration Elasticsearch)
• Go Testing & Benchmarking
• GitHub Actions (CI/CD)
• goreleaser & Makefile (release automation)
Detailed Architectural Elements to Capture
• The internal package boundary (tests under internal/integration-test) to indicate “not for public consumption.”
• The bench-marking harness reading benchmark files under benchmarks/tests.
• CI workflows invoking Makefile targets (test, bench, release).
• Example code as a consumer stub showing typical usage.