{"id":31537663,"url":"https://github.com/aviadklein/fluq","last_synced_at":"2026-05-15T21:01:48.933Z","repository":{"id":242151118,"uuid":"793940630","full_name":"AviadKlein/fluq","owner":"AviadKlein","description":"fluq provides a set of utilities and an intuitive API for constructing SQL queries programmatically in a python way, making it easier to build, read and maintain complex SQL statements","archived":false,"fork":false,"pushed_at":"2024-08-18T14:26:43.000Z","size":226,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-28T00:11:55.197Z","etag":null,"topics":["bigquery","package","python","python3","sql"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/fluq/","language":"Python","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/AviadKlein.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"supported_features.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-30T06:50:04.000Z","updated_at":"2024-08-18T14:26:39.000Z","dependencies_parsed_at":"2024-06-08T17:24:44.186Z","dependency_job_id":null,"html_url":"https://github.com/AviadKlein/fluq","commit_stats":null,"previous_names":["aviadklein/fluq"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/AviadKlein/fluq","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AviadKlein%2Ffluq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AviadKlein%2Ffluq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AviadKlein%2Ffluq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AviadKlein%2Ffluq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AviadKlein","download_url":"https://codeload.github.com/AviadKlein/fluq/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AviadKlein%2Ffluq/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278283509,"owners_count":25961311,"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-10-04T02:00:05.491Z","response_time":63,"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":["bigquery","package","python","python3","sql"],"created_at":"2025-10-04T08:08:54.927Z","updated_at":"2025-10-04T08:08:55.872Z","avatar_url":"https://github.com/AviadKlein.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FLUQ (FLUent Queries) - Python style API for heavy SQL users\n\nFLUQ provides a set of utilities and an intuitive API for constructing SQL queries programmatically, making it easier to build, read, and maintain complex SQL statements.\n\n## Installation\n\n```sh\npip install fluq\n```\n\n## Usage\n\nFluq was built borrowing from its inspiring packages to write SQL from left to right. \nThe package does not connect to data bases or run queries for the user, rather, it prevents users from having to create huge blobs of text that are hard to read, re-use and manage.\n\nWhere usually a query might look like this:\n```sql\nSELECT id -- starting from what columns we want\nFROM db.schema.table1 -- but we should start from where we want them\n```\n\nThe fluq way goes logically left-to-right:\n```python\nfrom fluq.sql import *\n\nquery = table(\"db.schema.table1\").select(\"id\")\n\nprint(query.sql) # returns: SELECT id FROM db.schema.table1\n```\n\n### The API:\n\n### Starting from tables: `table` method\n\nFluq allows you to start from sources\n\n```python\nfrom fluq.sql import table\n\nquery = table(\"db.schema.table1\") # this defines a Frame object\nprint(type(query)) \n# Output: \u003cclass 'fluq.frame.Frame'\u003e\n```\n`Frame` has many methods, among the rest is the `sql` property that renders the SQL code to run the query.\n\n```python\nprint(query.sql)\n# Output: SELECT * FROM db.schema.table1\n```\n\n#### Select specific columns\n```python\nfrom fluq.sql import table, col\n\nquery = table(\"db.schema.table1\").select(\"id\", \"name\")\n```\n\nOr, by using the `col` method:\n```python\nquery = table(\"db.schema.table1\").select(col(\"id\"), col(\"name\"))\n```\n\nBy using `col`, we get back a `Column` object, that allows to perform multiple operations over columns among the rest we can give them a different alias:\n\n```python\nquery = table(\"db.schema.table1\").select(\n    col(\"id\").as_(\"`customer id`\"), \n    col(\"name\").as_(\"`customer name`\"))\n\nprint(query.sql)\n# Output: SELECT id AS `customer id`, name AS `customer name` FROM db.schema.table1\n```\n\n\n### Specifying columns and literals\n\n* `col` - a method to represent a column by name\n* `lit` - a method to represent primitives (`str`, `bool`, `int`, `float`) as SQL literals\n* `select` - standalone method to select without a FROM clause (good for examples)\n\n```python\nfrom fluq.sql import select, col, lit\n\nquery = select(col(\"a\"))\nprint(type(query)) \n# Output: \u003cclass 'fluq.frame.Frame'\u003e\n\nprint(query.sql)\n# Output: SELECT a -- will result in an error over any db since \"a\" is not defined\n```\n\n### Selecting literals using `lit`\n```python\nfrom fluq.sql import select, lit\n\nquery = select(lit(2).as_(\"two\"))\n\nprint(query.sql)\n# Output: SELECT 2 AS two\n```\n\n### Arithmetics and functions:\n\n```python\nfrom fluq.sql import table, col, lit, functions as fn\nfrom datetime import date\n\n# create a literal with the current year\ncurrent_year = lit(date.today().year)\n\nquery = table(\"some.table\").select(\n    (current_year - col(\"year_joined\")).as_(\"years_since_joined\"),\n    (col(\"orders\")**2).as_(\"orders_squared\"),\n    col(\"sum_transactions\")*lit(1-0.17).as_(\"sum_transactions_net\"),\n    fn.exp(3)\n)\n\nprint(query.sql)\n# Output: SELECT 2024 - year_joined AS years_since_joined, POWER( orders, 2 ) AS orders_squared, sum_transactions * 0.83, EXP( 3 ) FROM some.table\n```\n\n### Logical operators: `==, \u003e, \u003e=, \u003c\u003e, \u003c, \u003c=, \u0026, |`:\n```python\nfrom fluq.sql import table, col\n\nquery = table(\"db.customers\").where(\n    (col(\"date_joined\") \u003e '2024-01-01') \u0026\n    (col(\"salary\") \u003c 5000) \u0026\n    (col(\"address\").is_not_null()) \u0026 \n    (col(\"country\") == 'US') \u0026\n    (col(\"indutry\").is_in('food', 'services'))\n).select(\"id\", \"name\", \"address\")\n\nprint(query.sql)\n# Output: SELECT id, name, address FROM db.customers WHERE ( ( ( ( date_joined \u003e '2024-01-01' ) AND ( salary \u003c 5000 ) ) AND ( address IS NOT NULL ) ) AND ( country = 'US' ) ) AND ( indutry IN ( 'food', 'services' ) )\n```\n\nNOTE: the `__eq__` magic method was 'kidnapped' in order to have a very python like approach. This is not void of potential issues. When comparing `Column` objects, use the `_equals` method instead of `==`.\n\n\n## Inspiration and rationale\n\nWe wished to create a left-to-right API to write the huge SQL queries that sometimes dominate python code, without working with SQLAlchemy or spark which is a pain on its own\n\n - [Spark](https://spark.apache.org/examples.html)\n - [Polars](https://docs.pola.rs/)\n\n## SQL flavour\n\nVersion 0.1.0 was built over BigQuery syntax, with the aim of supporting more flavours in future versions.\n\n## Contributing\n\nPlease be aware of the package dependency structure:\n![dependency structure](/fluq/module%20relationship.png)\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file.\n\n## Contact\nFor any inquiries, please contact [aviad.klein@gmail.com](mailto:aviad.klein@gmail.com) - don't hope for high SLA...","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviadklein%2Ffluq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faviadklein%2Ffluq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faviadklein%2Ffluq/lists"}