{"id":34691637,"url":"https://github.com/cloudresty/go-elastic","last_synced_at":"2025-12-24T22:00:01.225Z","repository":{"id":301978865,"uuid":"1010827043","full_name":"cloudresty/go-elastic","owner":"cloudresty","description":"A modern, production-ready Go package for Elasticsearch operations with environment-first configuration, ULID IDs, and comprehensive production features.","archived":false,"fork":false,"pushed_at":"2025-11-24T02:42:12.000Z","size":160,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-24T06:56:43.852Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://cloudresty.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudresty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-29T21:57:55.000Z","updated_at":"2025-08-11T10:10:41.000Z","dependencies_parsed_at":"2025-08-11T12:05:35.050Z","dependency_job_id":"06385e1d-8070-4446-8488-589f83d7c7e4","html_url":"https://github.com/cloudresty/go-elastic","commit_stats":null,"previous_names":["cloudresty/go-elastic"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cloudresty/go-elastic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudresty%2Fgo-elastic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudresty%2Fgo-elastic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudresty%2Fgo-elastic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudresty%2Fgo-elastic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudresty","download_url":"https://codeload.github.com/cloudresty/go-elastic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudresty%2Fgo-elastic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28010294,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T22:00:00.130Z","updated_at":"2025-12-24T22:00:01.218Z","avatar_url":"https://github.com/cloudresty.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go Elastic\n\n[Home](README.md) \u0026nbsp;/\n\n\u0026nbsp;\n\nA modern, production-ready Go package for Elasticsearch operations with environment-first configuration, ULID IDs, and comprehensive production features.\n\n\u0026nbsp;\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/cloudresty/go-elastic.svg)](https://pkg.go.dev/github.com/cloudresty/go-elastic)\n[![Go Tests](https://github.com/cloudresty/go-elastic/actions/workflows/ci.yaml/badge.svg)](https://github.com/cloudresty/go-elastic/actions/workflows/ci.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/cloudresty/go-elastic)](https://goreportcard.com/report/github.com/cloudresty/go-elastic)\n[![GitHub Tag](https://img.shields.io/github/v/tag/cloudresty/go-elastic?label=Version)](https://github.com/cloudresty/go-elastic/tags)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n\u0026nbsp;\n\n## Table of Contents\n\n- [Key Features](#key-features)\n- [Quick Start](#quick-start)\n  - [Installation](#installation)\n  - [Basic Usage](#basic-usage)\n  - [Environment Configuration](#environment-configuration)\n- [Documentation](#documentation)\n- [Why This Package?](#why-this-package)\n- [Production Usage](#production-usage)\n- [Requirements](#requirements)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n\u0026nbsp;\n\n## Key Features\n\n- **Best-in-Class Search Experience**: Three-pillar approach with fluent query builder, composable search API, and rich typed results\n- **Environment-First**: Configure via environment variables for cloud-native deployments\n- **Multiple ID Strategies**: Elasticsearch native (default), ULID, and custom ID generation\n- **Auto-Reconnection**: Intelligent retry with configurable exponential backoff\n- **Production-Ready**: Graceful shutdown, timeouts, health checks, bulk operations\n- **Resource-Oriented API**: Clean, idiomatic Go patterns with DocumentsService, IndicesService, ClusterService\n- **High Performance**: Optimized connection pooling, compression, and efficient operations\n- **Fully Tested**: Comprehensive test coverage with CI/CD pipeline\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Quick Start\n\n\u0026nbsp;\n\n### Installation\n\n```bash\ngo get github.com/cloudresty/go-elastic\n```\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Basic Usage\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"github.com/cloudresty/go-elastic\"\n    \"github.com/cloudresty/go-elastic/query\"\n)\n\ntype User struct {\n    Name  string `json:\"name\"`\n    Email string `json:\"email\"`\n    Age   int    `json:\"age\"`\n}\n\nfunc main() {\n    // Client - uses ELASTICSEARCH_* environment variables automatically\n    client, err := elastic.NewClient()\n    if err != nil {\n        panic(err)\n    }\n    defer client.Close()\n\n    ctx := context.Background()\n\n    // Index a document with auto-generated ID (Elasticsearch native by default)\n    user := User{\n        Name:  \"John Doe\",\n        Email: \"john@example.com\",\n        Age:   30,\n    }\n    result, err := client.Documents().Create(ctx, \"users\", user)\n    if err != nil {\n        panic(err)\n    }\n\n    // BEST-IN-CLASS SEARCH EXPERIENCE\n\n    // 1. Fluent Query Builder - Type-safe, readable queries\n    searchQuery := query.New().\n        Must(\n            query.Match(\"name\", \"John\"),\n            query.Range(\"age\").Gte(18).Build(),\n        ).\n        Filter(query.Term(\"active\", true))\n\n    // 2. Composable Search API - Rich options, clean syntax\n    typedDocs := elastic.For[User](client.Documents())\n    results, err := typedDocs.Search(\n        ctx,\n        searchQuery,\n        elastic.WithIndices(\"users\"),\n        elastic.WithSize(10),\n        elastic.WithSort(map[string]any{\"age\": \"desc\"}),\n        elastic.WithAggregation(\"avg_age\", elastic.NewAvgAggregation(\"age\")),\n    )\n\n    // 3. Rich, Typed Results - Effortless data extraction\n    if results.HasHits() {\n        users := results.Documents()     // []User - typed slice\n        firstUser, _ := results.First()  // User - typed document\n\n        results.Each(func(hit elastic.TypedHit[User]) {\n            println(hit.Source.Name, hit.Source.Email)\n        })\n\n        adults := results.Filter(func(u User) bool {\n            return u.Age \u003e= 18\n        })\n    }\n}\n```\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Environment Configuration\n\nSet environment variables for your deployment:\n\n```bash\nexport ELASTICSEARCH_HOSTS=localhost:9200\nexport ELASTICSEARCH_CONNECTION_NAME=my-service\nexport ELASTICSEARCH_TLS_ENABLED=false\nexport ELASTICSEARCH_CONNECT_TIMEOUT=10s\nexport ELASTICSEARCH_REQUEST_TIMEOUT=30s\n```\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [API Reference](docs/api-reference.md) | Complete function reference and usage patterns |\n| [Getting Started](docs/getting-started.md) | Step-by-step guide to get up and running quickly |\n| [Environment Configuration](docs/environment-configuration.md) | Environment variables and deployment configurations |\n| [Environment Variables](docs/environment-variables.md) | Complete reference of all environment variables |\n| [Production Features](docs/production-features.md) | Auto-reconnection, graceful shutdown, health checks, bulk operations |\n| [ID Generation](docs/id-generation.md) | Document ID generation strategies and performance considerations |\n| [Examples](docs/examples.md) | Comprehensive examples and usage patterns |\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Why This Package?\n\nThis package is designed for modern cloud-native applications that require robust, high-performance Elasticsearch operations. It leverages the power of Elasticsearch while providing a developer-friendly API that integrates seamlessly with environment-based configurations.\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Environment-First Design\n\nPerfect for modern cloud deployments with Docker, Kubernetes, and CI/CD pipelines. No more hardcoded connection strings.\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Smart ID Generation\n\nMultiple ID generation strategies: Elasticsearch native (default, recommended), ULID for sortable IDs, and custom IDs for specific use cases. Optimized for performance and shard distribution.\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Production-Ready\n\nBuilt-in support for high availability, graceful shutdown, automatic reconnection, and comprehensive timeout controls.\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Performance Optimized\n\nOptimized connection pooling, HTTP compression, configurable retry logic, and efficient ID generation for high-throughput scenarios.\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Production Usage\n\n```go\n// Use custom environment prefix for multi-service deployments\nclient, err := elastic.NewClient(elastic.FromEnvWithPrefix(\"SEARCH_\"))\nif err != nil {\n    log.Fatal(err)\n}\ndefer client.Close()\n\n// Health checks and monitoring\nif err := client.Ping(context.Background()); err != nil {\n    log.Printf(\"Elasticsearch connection failed: %v\", err)\n} else {\n    log.Println(\"Elasticsearch connection is healthy\")\n}\n\n// Graceful shutdown with signal handling\nshutdownManager := elastic.NewShutdownManager(\u0026elastic.ShutdownConfig{\n    Timeout: 30 * time.Second,\n})\nshutdownManager.SetupSignalHandler()\nshutdownManager.Register(client)\nshutdownManager.Wait() // Blocks until SIGINT/SIGTERM\n```\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Search Experience Philosophy\n\ngo-elastic delivers a **best-in-class search experience** built on three foundational pillars:\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Pillar 1: Fluent Query Builder\n\nBuild complex queries with a type-safe, chainable API that reads like natural language:\n\n```go\nimport \"github.com/cloudresty/go-elastic/query\"\n\n// Simple queries\nuserQuery := query.Term(\"status\", \"active\")\nsearchQuery := query.Match(\"title\", \"golang tutorial\")\n\n// Complex bool queries\ncomplexQuery := query.New().\n    Must(\n        query.MultiMatch(\"programming guide\", \"title\", \"description\"),\n        query.Range(\"rating\").Gte(4.0).Build(),\n    ).\n    Filter(\n        query.Term(\"published\", true),\n        query.Range(\"price\").Lte(50.0).Build(),\n    ).\n    Should(\n        query.Term(\"category\", \"programming\"),\n        query.Term(\"category\", \"technology\"),\n    ).\n    MinimumShouldMatch(1)\n```\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Pillar 2: Composable Search API\n\nA single, powerful search method with functional options for ultimate flexibility:\n\n```go\n// The ONLY way to search: clean, readable, type-safe\ntypedDocs := elastic.For[Product](client.Documents())\nresults, err := typedDocs.Search(\n    ctx,\n    queryBuilder,\n    elastic.WithIndices(\"products\"),\n    elastic.WithSize(20),\n    elastic.WithSort(map[string]any{\"rating\": \"desc\"}),\n    elastic.WithAggregation(\"categories\", elastic.NewTermsAggregation(\"category\")),\n)\n```\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n### Pillar 3: Rich, Typed Results\n\nSmart, structured responses with built-in helpers for effortless data extraction:\n\n```go\n// Get typed results using the fluent API\ntypedDocs := elastic.For[Product](client.Documents())\nresults, err := typedDocs.Search(ctx, queryBuilder, options...)\n\n// Rich result operations\nproducts := results.Documents()        // []Product - clean slice\ntotal := results.TotalHits()          // int - total count\nfirst, hasFirst := results.First()    // Product, bool - safe access\n\n// Functional operations\nexpensive := results.Filter(func(p Product) bool {\n    return p.Price \u003e 100.0\n})\n\nnames := results.Map(func(p Product) Product {\n    p.Name = strings.ToUpper(p.Name)\n    return p\n})\n\n// Iterate with metadata\nresults.Each(func(hit elastic.TypedHit[Product]) {\n    fmt.Printf(\"Product: %s (Score: %.2f)\\n\",\n        hit.Source.Name, *hit.Score)\n})\n```\n\n**The Result**: Search operations that are not just less verbose, but genuinely enjoyable to write and maintain.\n\n\u0026nbsp;\n\n🔝 [back to top](#go-elastic)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for your changes\n4. Ensure all tests pass\n5. Submit a pull request\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Security\n\nIf you discover a security vulnerability, please report it via email to [security@cloudresty.com](mailto:security@cloudresty.com).\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## Requirements\n\n- Go 1.24+ (recommended)\n- Elasticsearch 8.0+ (recommended)\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.\n\n🔝 [back to top](#go-elastic)\n\n\u0026nbsp;\n\n---\n\n\u0026nbsp;\n\nAn open source project brought to you by the [Cloudresty](https://cloudresty.com) team.\n\n[Website](https://cloudresty.com) \u0026nbsp;|\u0026nbsp; [LinkedIn](https://www.linkedin.com/company/cloudresty) \u0026nbsp;|\u0026nbsp; [BlueSky](https://bsky.app/profile/cloudresty.com) \u0026nbsp;|\u0026nbsp; [GitHub](https://github.com/cloudresty)\n\n\u0026nbsp;\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudresty%2Fgo-elastic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudresty%2Fgo-elastic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudresty%2Fgo-elastic/lists"}