{"id":13671621,"url":"https://github.com/databendlabs/jsonb","last_synced_at":"2025-12-30T00:03:22.643Z","repository":{"id":98452535,"uuid":"607721298","full_name":"datafuselabs/jsonb","owner":"datafuselabs","description":"JSONB implement in rust","archived":false,"fork":false,"pushed_at":"2024-04-25T12:03:48.000Z","size":891,"stargazers_count":60,"open_issues_count":5,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-04-29T22:55:51.386Z","etag":null,"topics":["json","jsonb","jsonpath"],"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/datafuselabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-02-28T14:48:00.000Z","updated_at":"2024-05-17T12:25:33.832Z","dependencies_parsed_at":"2023-07-13T19:25:14.464Z","dependency_job_id":"b7670be6-0d84-4655-813d-2580dfac13b0","html_url":"https://github.com/datafuselabs/jsonb","commit_stats":{"total_commits":17,"total_committers":3,"mean_commits":5.666666666666667,"dds":"0.23529411764705888","last_synced_commit":"82893b509eed117b80c7ead7704e040f26c0e7a1"},"previous_names":["datafuselabs/jsonb-rs"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datafuselabs%2Fjsonb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datafuselabs%2Fjsonb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datafuselabs%2Fjsonb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datafuselabs%2Fjsonb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datafuselabs","download_url":"https://codeload.github.com/datafuselabs/jsonb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":213650141,"owners_count":15618326,"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":["json","jsonb","jsonpath"],"created_at":"2024-08-02T09:01:14.679Z","updated_at":"2025-12-30T00:03:22.611Z","avatar_url":"https://github.com/datafuselabs.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# jsonb \u0026emsp; [![Build Status]][actions] [![Latest Version]][crates.io] [![Crate Downloads]][crates.io]\n\n[build status]: https://img.shields.io/github/actions/workflow/status/datafuselabs/jsonb/rust.yml?branch=main\n[actions]: https://github.com/datafuselabs/jsonb/actions?query=branch%3Amain\n[latest version]: https://img.shields.io/crates/v/jsonb.svg\n[crates.io]: https://crates.io/crates/jsonb\n[crate downloads]: https://img.shields.io/crates/d/jsonb.svg\n\n\n`jsonb` is a binary format `JSON` representation inspired by [PostgreSQL](https://www.postgresql.org/docs/current/datatype-json.html) and [CockroachDB](https://www.cockroachlabs.com/docs/stable/jsonb). It provides a fast, lightweight and easy-to-use API for working with `JSON` data.\n\n## Features\n\n- Good compatibility: `jsonb` fully supports the `JSON` standard and can be used to store complex data structures.\n- Fast performance: `jsonb` is designed for high performance, allowing you to work with large `JSON` data sets with ease.\n- Easy to use: `jsonb` provides a number of built-in functions to support various operations, and also supports the `JSONPath` syntax for selecting and extracting subset elements.\n- Safe and secure: `jsonb` is written in Rust, which provides memory and thread safety guarantees, making it a safe choice for handling sensitive data.\n\n## Encoding format\n\nThe `jsonb` encoding format is a tree-like structure. Each node contains a container header, a number of JEntry headers, and nested encoding values.\n\n- 32-bit container header. 3 bits identify the type of value, including `scalar`, `object` and `array`, and 29 bits identify the number of JEntries in the `array` or `object`. The root node of the `jsonb` value is always a container header.\n  - `scalar` container header: `0x20000000`\n  - `object` container header: `0x40000000`\n  - `array` container header: `0x80000000`\n- 32-bit JEntry header. 1 bit identifies whether the JEntry stores a length or an offset, 3 bits identify the type of value, including `null`, `string`, `number`, `false`, `true` and `container`, and the remaining 28 bits identify the length or offset of the encoding value.\n  - `null` JEntry header: `0x00000000`\n  - `string` JEntry header: `0x10000000`\n  - `number` JEntry header: `0x20000000`\n  - `false` JEntry header: `0x30000000`\n  - `true` JEntry header: `0x40000000`\n  - `container` JEntry header `0x50000000`\n- Encoding value. Different types of JEntry header have different encoding values.\n  - `null`, `true`, `false`: no encoding value, identified by the JEntry header.\n  - `string`: a normal UTF-8 string.\n  - `number`: an encoded number to represent uint64s, int64s and float64s.\n  - `container`: a nested `json` value with a recursive structure.\n\n#### An encoding example\n\n```text\n// JSON value\n[false, 10, {\"k\":\"v\"}]\n\n// JSONB encoding\n0x80000003    array container header (3 JEntries)\n0x30000000    false JEntry header (no encoding value)\n0x20000002    number JEntry header (encoding value length 2)\n0x5000000e    container JEntry header (encoding value length 14)\n0x500a        number encoding value (10)\n0x40000001    object container header (1 JEntry)\n0x10000001    string key JEntry header (encoding value length 1)\n0x10000001    string value JEntry header (encoding value length 1)\n0x6b          string encoding value (\"k\")\n0x76          string encoding value (\"v\")\n```\n\n## Jsonb value\n\nThe `jsonb` value is an enumeration that represents all kinds of `JSON` values and serves as an intermediate for converting other data types to the `jsonb` binary format value.\n\n```rust\n// jsonb value\n#[derive(Clone, PartialEq, Eq)]\npub enum Value\u003c'a\u003e {\n    Null,\n    Bool(bool),\n    String(Cow\u003c'a, str\u003e),\n    Number(Number),\n    Array(Vec\u003cValue\u003c'a\u003e\u003e),\n    Object(Object\u003c'a\u003e),\n}\n```\n\n## Built-in functions\n\n`jsonb` implements a number of commonly used built-in functions. Since most functions only focus on a subset of the total value, using container headers and JEntry headers to can efficiently skip over intermediate parts of the `jsonb` value. This avoids time-consuming deserialisation operations and provides very high performance. For more information, see https://docs.rs/jsonb/latest/jsonb/#functions\n\n## SQL/JSONPath\n\n[SQL/JSONPath](https://www.iso.org/standard/67367.html) is a query language used to select and extract a subset of elements from a `jsonb` value.\n\n#### Operators\n\nThe following operators have been implemented:\n\n| Operator                 | Description                                                  | Examples           |\n|--------------------------|--------------------------------------------------------------|--------------------|\n| `$`                      | The root element                                             | `$`                |\n| `@`                      | The current element in the filter expression                 | `$.event?(@ == 1)` |\n| `.*`                     | Selecting all elements in an Object                          | `$.*`              |\n| `.\u003cname\u003e`                | Selecting element that match the name in an Object           | `$.event`          |\n| `:\u003cname\u003e`                | Alias of `.\u003cname\u003e`                                           | `$:event`          |\n| `[\"\u003cname\u003e\"]`             | Alias of `.\u003cname\u003e`                                           | `$[\"event\"]`       |\n| `[*]`                    | Selecting all elements in an Array                           | `$[*]`             |\n| `[\u003cpos\u003e, ..]`            | Selecting 0-based `n-th` elements in an Array                | `$[1, 2]`          |\n| `[last - \u003cpos\u003e, ..]`     | Selecting `n-th` element before the last element in an Array | `$[0, last - 1]`   |\n| `[\u003cpos1\u003e to \u003cpos2\u003e, ..]` | Selecting all elements of a range in an Array                | `$[1 to last - 2]` |\n| `?(\u003cexpr\u003e)`              | Selecting all elements that matched the filter expression    | `$?(@.price \u003c 10)` |\n\n## Examples\n\n```rust\nfn main() {\n    let json = r#\"\n        {\n            \"name\":\"Fred\",\n            \"phones\":[\n                {\n                    \"type\":\"home\",\n                    \"number\":3720453\n                },\n                {\n                    \"type\": \"work\",\n                    \"number\":5062051\n                }\n            ]\n        }\"#;\n\n    let path = r#\"$.phones[*]?(@.number == 3720453)\"#;\n\n    // parse JSON string to jsonb value\n    let value = jsonb::parse_value(json.as_bytes()).unwrap();\n    // encode jsonb value to jsonb binary value\n    let jsonb = value.to_vec();\n    // parse JSONPath string\n    let json_path = jsonb::jsonpath::parse_json_path(path.as_bytes()).unwrap();\n    // select subset value from jsonb binary value\n    let mut sub_jsonb = Vec::new();\n    let mut sub_offsets = Vec::new();\n    jsonb::get_by_path(\u0026jsonb, json_path, \u0026mut sub_jsonb, \u0026mut sub_offsets);\n\n    // value={\"number\":3720453,\"type\":\"home\"}\n    println!(\"value={}\", jsonb::to_string(\u0026sub_jsonb));\n}\n```\n\n## Contributing\n\n`jsonb` is an open source project and all kinds of contributions are welcome! You can help with ideas, code or documentation.\n\n## License\n\nLicensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabendlabs%2Fjsonb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatabendlabs%2Fjsonb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatabendlabs%2Fjsonb/lists"}