{"id":30537790,"url":"https://github.com/ynqa/kuqu","last_synced_at":"2025-09-04T04:46:24.554Z","repository":{"id":303240097,"uuid":"1013535360","full_name":"ynqa/kuqu","owner":"ynqa","description":"SQL for Kubernetes resources","archived":false,"fork":false,"pushed_at":"2025-07-25T00:58:47.000Z","size":52,"stargazers_count":31,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-26T03:49:38.245Z","etag":null,"topics":["cli","kubernetes","sql"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ynqa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"ynqa"}},"created_at":"2025-07-04T04:20:33.000Z","updated_at":"2025-08-14T15:03:32.000Z","dependencies_parsed_at":"2025-07-06T15:03:00.912Z","dependency_job_id":"7923eda7-0da5-48c3-a99a-fce107f407db","html_url":"https://github.com/ynqa/kuqu","commit_stats":null,"previous_names":["ynqa/kuqu"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ynqa/kuqu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynqa%2Fkuqu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynqa%2Fkuqu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynqa%2Fkuqu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynqa%2Fkuqu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ynqa","download_url":"https://codeload.github.com/ynqa/kuqu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ynqa%2Fkuqu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273554242,"owners_count":25126310,"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-09-04T02:00:08.968Z","response_time":61,"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":["cli","kubernetes","sql"],"created_at":"2025-08-27T19:41:28.129Z","updated_at":"2025-09-04T04:46:24.536Z","avatar_url":"https://github.com/ynqa.png","language":"Rust","funding_links":["https://github.com/sponsors/ynqa"],"categories":[],"sub_categories":[],"readme":"# kuqu\n\nSQL for Kubernetes resources.\n\n## Concept\n\n*kuqu* is a tool that allows you to query Kubernetes resources using SQL-like syntax.\nBy leveraging [Apache DataFusion](https://datafusion.apache.org/)\n(hereinafter referred to as DataFusion),\nit treats resources within a Kubernetes cluster as tabular data,\nenabling you to perform operations such as filtering, aggregation, and joins\nusing familiar SQL syntax.\n\nWhile traditional kubectl commands make it difficult to search for resources\nwith complex conditions or perform aggregations,\n*kuqu* allows you to analyze Kubernetes resources with the same intuitive approach\nas working with databases.\nFor example, you can aggregate the number of Pods that meet specific conditions\nor join and display information across multiple resource types.\n\n## Features\n\n- [x] High-performance query execution with DataFusion\n    - [x] Querying Kubernetes resources using SQL syntax\n    - [x] Automatic resource structure recognition through dynamic schema inference\n    - [x] Direct access to JSON fields (e.g., `spec.nodeName`)\n    - [x] JOIN operations between multiple resource types\n    - [ ] Query result export functionality\n    - [ ] User-defined function (UDF) definition and registration\n          (is this even possible?)\n- [x] Support for namespace-scoped and cluster-scoped resources\n    - [ ] AllNamespace support\n- [x] Custom Resource Definition (CRD) support\n- [ ] Change detection (i.e., watch) support for query results\n- [ ] Provide as a Rust library\n- [ ] Provide as a kubectl plugin\n- [ ] Query for manifest files\n    - e.g. For comparison with the actual resource state\n- [ ] REPL\n    - [ ] Query result caching mechanism\n    - [ ] Query history and favorites functionality\n- [ ] Visualization (is this even possible?)\n    - [ ] Colored output\n    - [ ] Automatic table width adjustment\n    - [ ] Table scrolling functionality\n- [ ] Configuration file\n    - [ ] Alias\n\n## Installation\n\n### Homebrew\n\n```bash\nbrew install ynqa/tap/kuqu\n```\n\n### Cargo\n\n```bash\ncargo install kuqu\n\n# Or from source (at kuqu root)\ncargo install --path .\n```\n\n### Shell\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf https://github.com/ynqa/kuqu/releases/download/v0.1.0/kuqu-installer.sh | sh\n```\n\n## Examples\n\n```bash\n# List all running pods\nkuqu \"SELECT metadata.name, metadata.namespace FROM pods WHERE status.phase = 'Running'\"\n\n# List all services like redis\nkuqu \"SELECT metadata.name FROM services WHERE metadata.name LIKE '%redis%'\"\n\n# Example for a CRD\nkuqu \"SELECT metadata.name FROM 'envoyproxies.gateway.envoyproxy.io'\"\n\n# List deployments with ready replicas\nkuqu \"SELECT metadata.name, spec.replicas, status.readyReplicas FROM deployments \n     WHERE spec.replicas == status.readyReplicas\"\n\n# List all pods with their node names and instance types\nkuqu \"SELECT pod.metadata.name, pod.spec.nodeName, \n            node.metadata.labels.'node.kubernetes.io/instance-type' \n     FROM pod JOIN node ON pod.spec.nodeName == node.metadata.name\"\n```\n\n## SQL Syntax\n\nSQL syntax available in *kuqu* conforms to DataFusion.\nDataFusion is a high-performance query engine that provides many extended features\nin addition to standard SQL functionality.\n\nFor detailed information about supported SQL syntax,\nplease refer to the official DataFusion documentation:\n\n**[DataFusion SQL Reference](https://datafusion.apache.org/user-guide/sql/index.html)**\n\nThis documentation provides detailed explanations of all available SQL features,\nincluding SELECT statements, WHERE clauses, JOIN operations, aggregate functions,\nwindow functions, and more.\n\n\u003e [!NOTE]\n\u003e *kuqu* does not comprehensively test all DataFusion SQL features,\n\u003e so some queries or syntax may not work as expected.\n\u003e If you encounter issues, please use more basic SQL syntax\n\u003e or report them as GitHub Issues.\n\n## Schema Inference\n\nInstead of using Kubernetes' `/openapi/v3` endpoint,\n*kuqu* dynamically infers schemas from actual resource data.\n\nThe reason for this design decision is that the OpenAPI specification\ncannot deterministically resolve schemas for dynamically determined keys\nin fields with `additionalProperties=true`,\nsuch as `metadata.labels` and `metadata.annotations`.\nThese fields allow users to add arbitrary key-value pairs at runtime,\nmaking it difficult to define schemas in advance.\n\nBy adopting dynamic schema inference,\n*kuqu* enables SQL queries against all fields that exist in actual resources\n(including custom labels and annotations),\nproviding a more flexible and practical query experience.\n\nHowever, since schemas are inferred at query execution time,\nqueries may take longer when there are many resources\nor when resources with complex structures exist\n(we are considering mechanisms to limit the number of resources\nused for schema inference).\n\n## Table Specification\n\nIn *kuqu*, Kubernetes resources are treated as SQL tables.\nTable name (resource name) specification supports flexible formats.\n\n### Table Format\n\n```sql\n-- Basic format: resource name only (uses default namespace)\nSELECT * FROM pods;\n\n-- Namespace specification: resource_name/namespace_name\nSELECT * FROM 'pods/kube-system';\n\n-- Non-namespaced resources (namespace specification is ignored)\nSELECT * FROM nodes;\n```\n\n### Resource Name Formats\n\n*kuqu* allows you to specify Kubernetes resources in multiple ways:\n\n1. **Basic resource names**: `pods`, `deployments`, `services`\n2. **Singular names**: `pod`, `deployment`, `service`\n3. **Short names**: `po`, `deploy`, `svc`\n4. **Group-qualified resource names**: `deployments.apps`,\n   `rolebindings.rbac.authorization.k8s.io`\n\n## Acknowledgements\n\nThis project was made possible thanks to the valuable advice and insights from [@zimagen](https://github.com/zimagen).\nThose played a crucial role in shaping the ideas behind this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fynqa%2Fkuqu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fynqa%2Fkuqu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fynqa%2Fkuqu/lists"}