{"id":13513449,"url":"https://github.com/postgrespro/jsquery","last_synced_at":"2025-05-15T06:08:43.580Z","repository":{"id":16805951,"uuid":"19564845","full_name":"postgrespro/jsquery","owner":"postgrespro","description":"JsQuery – json query language with GIN indexing support","archived":false,"fork":false,"pushed_at":"2025-01-27T09:59:01.000Z","size":568,"stargazers_count":705,"open_issues_count":10,"forks_count":49,"subscribers_count":63,"default_branch":"master","last_synced_at":"2025-05-11T18:11:25.655Z","etag":null,"topics":["gin","json","json-query","jsonb","query-language"],"latest_commit_sha":null,"homepage":"","language":"C","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/postgrespro.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":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-08T07:40:51.000Z","updated_at":"2025-05-08T03:43:16.000Z","dependencies_parsed_at":"2024-01-13T19:23:21.405Z","dependency_job_id":"a655d4c2-da3c-4218-ad99-912660bad30d","html_url":"https://github.com/postgrespro/jsquery","commit_stats":{"total_commits":164,"total_committers":16,"mean_commits":10.25,"dds":0.5914634146341464,"last_synced_commit":"9583d5b6914b5d89483ced4fcee428d5fccbe3c2"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgrespro%2Fjsquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgrespro%2Fjsquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgrespro%2Fjsquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postgrespro%2Fjsquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postgrespro","download_url":"https://codeload.github.com/postgrespro/jsquery/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254283350,"owners_count":22045141,"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":["gin","json","json-query","jsonb","query-language"],"created_at":"2024-08-01T05:00:25.857Z","updated_at":"2025-05-15T06:08:39.432Z","avatar_url":"https://github.com/postgrespro.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/postgrespro/jsquery.svg?branch=master)](https://travis-ci.org/postgrespro/jsquery)\n[![codecov](https://codecov.io/gh/postgrespro/jsquery/branch/master/graph/badge.svg)](https://codecov.io/gh/postgrespro/jsquery)\n[![GitHub license](https://img.shields.io/badge/license-PostgreSQL-blue.svg)](https://raw.githubusercontent.com/postgrespro/jsquery/master/LICENSE)\n\nJsQuery – json query language with GIN indexing support\n=======================================================\n\nIntroduction\n------------\n\nJsQuery – is a language to query jsonb data type, introduced in PostgreSQL\nrelease 9.4.\n\nIt's primary goal is to provide an additional functionality to jsonb\n(currently missing in PostgreSQL), such as a simple and effective way\nto search in nested objects and arrays, more comparison operators with\nindexes support. We hope, that jsquery will be eventually a part of\nPostgreSQL.\n\nJsquery is released as jsquery data type (similar to tsquery) and @@\nmatch operator for jsonb.\n\nAuthors\n-------\n\n * Teodor Sigaev \u003cteodor@sigaev.ru\u003e, Postgres Professional, Moscow, Russia\n * Alexander Korotkov \u003caekorotkov@gmail.com\u003e, Postgres Professional, Moscow, Russia\n * Oleg Bartunov \u003coleg@sai.msu.su\u003e, Postgres Professional, Moscow, Russia\n\nAvailability\n------------\n\nJsQuery is realized as an extension and not available in default PostgreSQL\ninstallation. It is available from\n[github](https://github.com/postgrespro/jsquery)\nunder the same license as\n[PostgreSQL](https://www.postgresql.org/about/licence/)\nand supports PostgreSQL 9.4+.\n\nRegards\n-------\n\nDevelopment was sponsored by [Wargaming.net](http://wargaming.net).\n\nInstallation\n------------\n\nJsQuery is PostgreSQL extension which requires PostgreSQL 9.4 or higher.\nBefore build and install you should ensure following:\n    \n * PostgreSQL version is 9.4 or higher.\n * You have development package of PostgreSQL installed or you built\n   PostgreSQL from source.\n * You have flex and bison installed on your system. JsQuery was tested on\n   flex 2.5.37-2.5.39, bison 2.7.12.\n * Your PATH variable is configured so that pg\\_config command available, or set PG_CONFIG variable.\n    \nTypical installation procedure may look like this:\n    \n    $ git clone https://github.com/postgrespro/jsquery.git\n    $ cd jsquery\n    $ make USE_PGXS=1\n    $ sudo make USE_PGXS=1 install\n    $ make USE_PGXS=1 installcheck\n    $ psql DB -c \"CREATE EXTENSION jsquery;\"\n\nJSON query language\n-------------------\n\nJsQuery extension contains `jsquery` datatype which represents whole JSON query\nas a single value (like `tsquery` does for fulltext search). The query is an\nexpression on JSON-document values.\n\nSimple expression is specified as `path binary_operator value` or\n`path unary_operator`. See following examples.\n\n * `x = \"abc\"` – value of key \"x\" is equal to \"abc\";\n * `$ @\u003e [4, 5, \"zzz\"]` – the JSON document is an array containing values\n    4, 5 and \"zzz\";\n * `\"abc xyz\" \u003e= 10` – value of key \"abc xyz\" is greater than or equal to 10;\n * `volume IS NUMERIC` – type of key \"volume\" is numeric.\n * `$ = true` – the whole JSON document is just a true.\n * `similar_ids.@# \u003e 5` – similar\\_ids is an array or object of length greater\n   than 5;\n * `similar_product_ids.# = \"0684824396\"` – array \"similar\\_product\\_ids\"\n   contains string \"0684824396\".\n * `*.color = \"red\"` – there is object somewhere which key \"color\" has value \"red\".\n * `foo = *` – key \"foo\" exists in object.\n\nPath selects a set of JSON values to be checked using given operators. In\nthe simplest case path is just a key name. In general path is key names and\nplaceholders combined by dot signs. Path can use the following placeholders:\n\n * `#` – any index of an array;\n * `#N` – N-th index of an array;\n * `%` – any key of an object;\n * `*` – any sequence of array indexes and object keys;\n * `@#` – length of array or object, may only be used as the last component of\n    a path;\n * `$` – the whole JSON document as single value, may only be the whole path.\n\nExpression is true when operator is true against at least one value selected\nby path.\n\nKey names could be given either with or without double quotes. Key names\nwithout double quotes may not contain spaces, start with a number or match\na jsquery keyword.\n\nThe supported binary operators are:\n\n * Equality operator: `=`;\n * Numeric comparison operators: `\u003e`, `\u003e=`, `\u003c`, `\u003c=`;\n * Search in the list of scalar values using `IN` operator;\n * Array comparison operators: `\u0026\u0026` (overlap), `@\u003e` (contains),\n   `\u003c@` (contained in).\n\nThe supported unary operators are:\n\n * Check for existence operator: `= *`;\n * Check for type operators: `IS ARRAY`, `IS NUMERIC`, `IS OBJECT`, `IS STRING`\n   and `IS BOOLEAN`.\n\nExpressions can be complex. Complex expression is a set of expressions\ncombined by logical operators (`AND`, `OR`, `NOT`) and grouped using braces.\n\nExamples of complex expressions:\n\n * `a = 1 AND (b = 2 OR c = 3) AND NOT d = 1`\n * `x.% = true OR x.# = true`\n\nPrefix expressions are expressions given in the form `path (subexpression)`.\nIn this case path selects JSON values to be checked using the given subexpression.\nCheck results are aggregated in the same way as in simple expressions.\n\n * `#(a = 1 AND b = 2)` – exists element of array which a key is 1 and b key is 2\n * `%($ \u003e= 10 AND $ \u003c= 20)` – exists object key which values is between 10 and 20\n\nPath can also contain the following special placeholders with \"every\" semantics:\n\n * `#:` – every index of an array;\n * `%:` – every key of an object;\n * `*:` – every sequence of array indexes and object keys.\n\nConsider following example.\n\n    %.#:($ \u003e= 0 AND $ \u003c= 1)\n\nThis example could be read as following: there is at least one key whose value\nis an array of numerics between 0 and 1.\n\nWe can rewrite this example in the following form with extra braces:\n\n    %(#:($ \u003e= 0 AND $ \u003c= 1))\n\nThe first placeholder `%` checks that the expression in braces is true for at least\none value in the object. The second placeholder `#:` checks if the value is an array\nand that all its elements satisfy the expressions in braces.\n\nWe can rewrite this example without the `#:` placeholder as follows:\n\n    %(NOT #(NOT ($ \u003e= 0 AND $ \u003c= 1)) AND $ IS ARRAY)\n\nIn this example we transform the assertion that every element of array satisfy some\ncondition to an assertion that there are no elements which don't satisfy the same\ncondition.\n\nSome examples of using paths:\n\n * `numbers.#: IS NUMERIC` – every element of \"numbers\" array is numeric.\n * `*:($ IS OBJECT OR $ IS BOOLEAN)` – JSON is a structure of nested objects\n   with booleans as leaf values.\n * `#:.%:($ \u003e= 0 AND $ \u003c= 1)` – each element of array is an object containing\n   only numeric values between 0 and 1.\n * `documents.#:.% = *` – \"documents\" is an array of objects containing at least\n   one key.\n * `%.#: ($ IS STRING)` – JSON object contains at least one array of strings.\n * `#.% = true` – at least one array element is an object which contains at least\n   one \"true\" value.\n\nThe use of path operators and braces need some further explanation. When the same path\noperators are used multiple times, they may refer to different values. If you want them\nto always refer to the same value, you must use braces and the `$` operator. For example:\n\n * `# \u003c 10 AND # \u003e 20` – an element less than 10 exists, and another element\n   greater than 20 exists.\n * `#($ \u003c 10 AND $ \u003e 20)` – an element which is both less than 10 and greater\n   than 20 exists (impossible).\n * `#($ \u003e= 10 AND $ \u003c= 20)` – an element between 10 and 20 exists.\n * `# \u003e= 10 AND # \u003c= 20` – an element greater or equal to 10 exists, and another\n   element less or equal to 20 exists. Please note that this query also can be\n   satisfied by an array with no elements between 10 and 20, for instance [0,30].\n\nSame rules apply when searching inside objects and branch structures.\n\nType checking operators and \"every\" placeholders are useful for document\nschema validation. JsQuery matchig operator `@@` is immutable and can be used\nin CHECK constraint. See following example.\n\n```sql\nCREATE TABLE js (\n    id serial,\n    data jsonb,\n    CHECK (data @@ '\n        name IS STRING AND\n        similar_ids.#: IS NUMERIC AND\n        points.#:(x IS NUMERIC AND y IS NUMERIC)'::jsquery));\n```\n\nIn this example the check constraint validates that in the \"data\" jsonb column\nthe value of the \"name\" key is a string, the value of the \"similar_ids\" key is an array of numerics,\nand the value of the \"points\" key is an array of objects which contain numeric values in\n\"x\" and \"y\" keys.\n\nSee our\n[pgconf.eu presentation](http://www.sai.msu.su/~megera/postgres/talks/pgconfeu-2014-jsquery.pdf)\nfor more examples.\n\nGIN indexes\n-----------\n\nJsQuery extension contains two operator classes (opclasses) for GIN which\nprovide different kinds of query optimization.\n\n * jsonb\\_path\\_value\\_ops\n * jsonb\\_value\\_path\\_ops\n\nIn each of two GIN opclasses jsonb documents are decomposed into entries. Each\nentry is associated with a particular value and its path. The difference between\nopclasses is in the entry representation, comparison and usage for search\noptimization.\n\nFor example, the jsonb document\n`{\"a\": [{\"b\": \"xyz\", \"c\": true}, 10], \"d\": {\"e\": [7, false]}}`\nwould be decomposed into following entries:\n\n * \"a\".#.\"b\".\"xyz\"\n * \"a\".#.\"c\".true\n * \"a\".#.10\n * \"d\".\"e\".#.7\n * \"d\".\"e\".#.false\n\nSince JsQuery doesn't support searching in a particular array index, we consider\nall array elements to be equivalent. Thus, each array element is marked with\nthe same `#` sign in its path.\n\nMajor problem in the entries representation is its size. In the given example\nthe key \"a\" is presented three times. In large branchy documents with long\nkeys sizes of naive entries, the representation becomes unreasonably large.\nBoth opclasses address this issue, but in slightly different ways.\n\n### jsonb\\_path\\_value\\_ops\n\njsonb\\_path\\_value\\_ops represents entry as pair of path hash and value.\nFollowing pseudocode illustrates it:\n\n    (hash(path_item_1.path_item_2. ... .path_item_n); value)\n\nWhen comparison entries, the path hash is the higher part of entry and the value is\nthe lower part. This determines the features of this opclass. Since the path\nis hashed and it's the higher part of the entry, we need to know the full path to\na value in order to use the it for searching. However, once the path is specified\nwe can use both exact and range searches very efficiently.\n\n### jsonb\\_value\\_path\\_ops\n\njsonb\\_value\\_path\\_ops represents entry as pair of the value and a bloom filter\nof paths:\n\n    (value; bloom(path_item_1) | bloom(path_item_2) | ... | bloom(path_item_n))\n\nIn comparison of entries value is the higher part of entry and bloom filter of\npath is its lower part. This determines the features of this opclass. Since\nthe value is the higher part of an entry, we can only perform exact value search\neffectively. A search over a range of values is possible as well, but we have to\nfilter all the the different paths where matching values occur. The Bloom filter\nover path items allows the index to be used for conditions containing `%` and `*` in\ntheir paths.\n\n### Query optimization\n\nJsQuery opclasses perform complex query optimization. It's valuable for a\ndeveloper or administrator to see the result of such optimization.\nUnfortunately, opclasses aren't allowed to put any custom output in an\nEXPLAIN. That's why JsQuery provides these functions to let you see\nhow particular opclass optimizes given query:\n\n * gin\\_debug\\_query\\_path\\_value(jsquery) – for jsonb\\_path\\_value\\_ops\n * gin\\_debug\\_query\\_value\\_path(jsquery) – for jsonb\\_value\\_path\\_ops\n\nThe result of these functions is a textual representation of the query tree\nwhere leaves are GIN search entries. Following examples show different results of\nquery optimization by different opclasses:\n\n    # SELECT gin_debug_query_path_value('x = 1 AND (*.y = 1 OR y = 2)');\n     gin_debug_query_path_value\n    ----------------------------\n     x = 1 , entry 0           +\n\n    # SELECT gin_debug_query_value_path('x = 1 AND (*.y = 1 OR y = 2)');\n     gin_debug_query_value_path\n    ----------------------------\n     AND                       +\n       x = 1 , entry 0         +\n       OR                      +\n         *.y = 1 , entry 1     +\n         y = 2 , entry 2       +\n\nUnfortunately, jsonb have no statistics yet. That's why JsQuery optimizer has\nto do imperative decision while selecting conditions to be evaluated using\nindex. This decision is made by assuming that some condition types are less\nselective than others. The optimizer divides conditions into following selectivity\nclasses (listed in descending order of selectivity):\n\n 1. Equality (x = c)\n 2. Range (c1 \u003c x \u003c c2)\n 3. Inequality (x \u003e c)\n 4. Is (x is type)\n 5. Any (x = \\*)\n\nThe optimizer avoids index evaluation of less selective conditions when possible.\nFor example, in the `x = 1 AND y \u003e 0` query `x = 1` is assumed to be more\nselective than `y \u003e 0`. That's why the index isn't used for evaluation of `y \u003e 0`.\n\n    # SELECT gin_debug_query_path_value('x = 1 AND y \u003e 0');\n     gin_debug_query_path_value\n    ----------------------------\n     x = 1 , entry 0           +\n\nWith the lack of statistics, decisions made by optimizer can be inaccurate. That's\nwhy JsQuery supports hints. The comments `/*-- index */` or `/*-- noindex */`\nplaced in the conditions force the optimizer to use or not use an index\ncorrespondingly:\n\n    SELECT gin_debug_query_path_value('x = 1 AND y /*-- index */ \u003e 0');\n     gin_debug_query_path_value\n    ----------------------------\n     AND                       +\n       x = 1 , entry 0         +\n       y \u003e 0 , entry 1         +\n\n    SELECT gin_debug_query_path_value('x /*-- noindex */ = 1 AND y \u003e 0');\n     gin_debug_query_path_value\n     ----------------------------\n      y \u003e 0 , entry 0           +\n\nContribution\n------------\n\nPlease note that JsQuery is still under development. While it's\nstable and tested, it may contain some bugs. Don't hesitate to create\n[issues at github](https://github.com/postgrespro/jsquery/issues) with your\nbug reports.\n\nIf there's some functionality you'd like to see added to JsQuery and you feel\nlike you can implement it, then you're welcome to make pull requests.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostgrespro%2Fjsquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostgrespro%2Fjsquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostgrespro%2Fjsquery/lists"}