{"id":22117722,"url":"https://github.com/kineticcafe/csquery","last_synced_at":"2025-03-24T06:14:29.466Z","repository":{"id":57487454,"uuid":"141854475","full_name":"KineticCafe/csquery","owner":"KineticCafe","description":"A simple CloudSearch structured search syntax query builder for Elixir.","archived":false,"fork":false,"pushed_at":"2019-07-06T22:30:34.000Z","size":23,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-02T21:47:28.953Z","etag":null,"topics":["aws-cloudsearch","elixir","query-builder"],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KineticCafe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"Contributing.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-07-22T00:26:15.000Z","updated_at":"2025-01-19T03:14:20.000Z","dependencies_parsed_at":"2022-09-01T23:02:24.948Z","dependency_job_id":null,"html_url":"https://github.com/KineticCafe/csquery","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KineticCafe%2Fcsquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KineticCafe%2Fcsquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KineticCafe%2Fcsquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KineticCafe%2Fcsquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KineticCafe","download_url":"https://codeload.github.com/KineticCafe/csquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245217936,"owners_count":20579300,"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","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":["aws-cloudsearch","elixir","query-builder"],"created_at":"2024-12-01T13:38:54.452Z","updated_at":"2025-03-24T06:14:29.434Z","avatar_url":"https://github.com/KineticCafe.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CSQuery\n\n[![Build Status][build_status_svg]][build status]\n\nA query builder for the AWS [CloudSearch][] [structured search\nsyntax][sss]. This query builder is largely inspired by [csquery for\nPython][csquery.py].\n\n## Installation\n\n`CSQuery` is a pure library, so it only needs to be added to your dependencies.\n\n```elixir\n@deps [\n  csquery: \"~\u003e 1.0\"\n  # OR: {:csquery, github: \"KineticCafe/csquery\"}\n]\n\ndef deps: @deps\n```\n\n## Introduction and Usage\n\n`CSQuery` is a structured search syntax query builder for AWS CloudSearch. It\nserves one purpose: build a structured query. It does not integrate with\nany networking library. The queries built with this library are raw input to\nthe `q` parameter of a CloudSearch request when `q.parser=structured`.\n\nIt does not support, and will not support, other query parsers provided by AWS\nCloudSearch (simple, lucene, or dismax). Other libraries may be able to provide\nstructured query building for those parsers.\n\nCSQuery provides two ways of building a query:\n\n*   A DSL-style approach like the Python implementation:\n\n    ```elixir\n    iex\u003e and!([title: \"star\", actor: \"Harrison Ford\", boost: 2]) |\u003e to_query()\n    \"(and boost=2 title:'star' actor:'Harrison Ford')\"\n    ```\n\n*   A structured parser:\n\n    ```elixir\n    iex\u003e parse(and: [title: \"star\", actor: \"Harrison Ford\", boost: 2]) |\u003e\n    ...\u003e to_query()\n    \"(and boost=2 title:'star' actor:'Harrison Ford')\"\n    ```\n\nThe structured parser feels like it fits better in the style of Elixir,\nespecially with complex queries (see below). Both are supported (and are\nimplemented the same way). The documentation for each operator is on the\nDSL-like functions below (as with `and!/1`), but examples are given for both\nforms.\n\n### Complex Queries\n\nA complex query can be built with sufficient nesting:\n\n```elixir\niex\u003e and!([\n...\u003e  not!([\"test\", field: \"genres\"]),\n...\u003e  or!([\n...\u003e    term!([\"star\", field: \"title\", boost: 2]),\n...\u003e    term!([\"star\", field: \"plot\"])\n...\u003e  ])\n...\u003e ]) |\u003e to_query\n\"(and (not field=genres 'test') (or (term boost=2 field=title 'star') (term field=plot 'star')))\"\n\niex\u003e parse(and: [\n...\u003e  not: [\"test\", field: \"genres\"],\n...\u003e  or: [\n...\u003e    term: [\"star\", field: \"title\", boost: 2],\n...\u003e    term: [\"star\", field: \"plot\"]\n...\u003e  ]\n...\u003e ]) |\u003e to_query\n\"(and (not field=genres 'test') (or (term boost=2 field=title 'star') (term field=plot 'star')))\"\n```\n\nIt is also possible to mix and match the forms (but please avoid this):\n\n```elixir\niex\u003e parse(and: [\n...\u003e  not!([\"test\", field: \"genres\"]),\n...\u003e  or: [\n...\u003e    term: [\"star\", field: \"title\", boost: 2],\n...\u003e    term: [\"star\", field: \"plot\"]\n...\u003e  ]\n...\u003e ]) |\u003e to_query\n\"(and (not field=genres 'test') (or (term boost=2 field=title 'star') (term field=plot 'star')))\"\n```\n\n### Supported Field Value Data Types:\n\n*   Strings:\n\n    ```elixir\n    iex\u003e term!([\"STRING\"]) |\u003e to_query\n    \"(term 'STRING')\"\n    ```\n\n*   Ranges:\n\n    ```elixir\n    iex\u003e range!([1..2]) |\u003e to_query\n    \"(range [1,2])\"\n\n    iex\u003e range!([{nil, 10}]) |\u003e to_query\n    \"(range {,10])\"\n\n    iex\u003e range!([{10, nil}]) |\u003e to_query\n    \"(range [10,})\"\n\n    iex\u003e range!([CSQuery.Range.new(%{first?: 0, last?: 101})]) |\u003e to_query\n    \"(range {0,101})\"\n    ```\n\n*   Numbers:\n\n    ```elixir\n    iex\u003e term!([10]) |\u003e to_query\n    \"(term 10)\"\n\n    iex\u003e term!([3.14159]) |\u003e to_query\n    \"(term 3.14159)\"\n    ```\n\n*   DateTime (`t:DateTime.t/0`):\n\n    ```elixir\n    iex\u003e %DateTime{\n    ...\u003e  year: 2018, month: 7, day: 21,\n    ...\u003e  hour: 17, minute: 55, second: 0,\n    ...\u003e  time_zone: \"America/Toronto\", zone_abbr: \"EST\",\n    ...\u003e  utc_offset: -14_400, std_offset: 0\n    ...\u003e } |\u003e List.wrap() |\u003e term! |\u003e to_query\n    \"(term '2018-07-21T17:55:00-04:00')\"\n    ```\n\n*   Terms:\n\n    ```elixir\n    iex\u003e or!([\"(and 'star' 'wars')\", \"(and 'star' 'trek')\"]) |\u003e to_query\n    \"(or (and 'star' 'wars') (and 'star' 'trek'))\"\n    ```\n\n## ExAws.CloudSearch Support\n\nThe forthcoming ExAws.CloudSearch library will recognize CSQuery-generated\nexpressions and configure its query request so that the structured parser is\nused.\n\n## Community and Contributing\n\nWe welcome your contributions, as described in [Contributing.md][]. Like all\nKinetic Cafe [open source projects][], is under the Kinetic Cafe Open Source\n[Code of Conduct][kccoc].\n\n[build status svg]: https://travis-ci.org/KineticCafe/csquery.svg?branch=master\n[build status]: https://travis-ci.org/KineticCafe/csquery\n[Hex.pm]: https://hex.pm\n[Contributing.md]: Contributing.md\n[open source projects]: https://github.com/KineticCafe\n[kccoc]: https://github.com/KineticCafe/code-of-conduct\n[CloudSearch]: https://docs.aws.amazon.com/cloudsearch/\n[sss]: https://docs.aws.amazon.com/cloudsearch/latest/developerguide/search-api.html#structured-search-syntax\n[csquery.py]: https://github.com/tell-k/csquery\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkineticcafe%2Fcsquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkineticcafe%2Fcsquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkineticcafe%2Fcsquery/lists"}