Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve readme with examples and operator usage #45

Merged
merged 1 commit into from
Sep 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
/target
Cargo.lock
.idea
45 changes: 44 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,47 @@ To use these functions, you'll just need to call:
```rust
datafusion_functions_json::register_all(&mut ctx)?;
```

To register the below JSON functions in your `SessionContext`.

# Examples

```sql
-- Create a table with a JSON column stored as a string
CREATE TABLE test_table (id INT, json_col VARCHAR) AS VALUES
(1, '{}'),
(2, '{ "a": 1 }'),
(3, '{ "a": 2 }'),
(4, '{ "a": 1, "b": 2 }'),
(5, '{ "a": 1, "b": 2, "c": 3 }');

-- Check if each document contains the key 'b'
SELECT id, json_contains(json_col, 'b') as json_contains FROM test_table;
-- Results in
-- +----+---------------+
-- | id | json_contains |
-- +----+---------------+
-- | 1 | false |
-- | 2 | false |
-- | 3 | false |
-- | 4 | true |
-- | 5 | true |
-- +----+---------------+

-- Get the value of the key 'a' from each document
SELECT id, json_col->'a' as json_col_a FROM test_table

-- +----+------------+
-- | id | json_col_a |
-- +----+------------+
-- | 1 | {null=} |
-- | 2 | {int=1} |
-- | 3 | {int=2} |
-- | 4 | {int=1} |
-- | 5 | {int=1} |
-- +----+------------+
```


## Done

* [x] `json_contains(json: str, *keys: str | int) -> bool` - true if a JSON string has a specific key (used for the `?` operator)
Expand All @@ -27,6 +65,11 @@ To register the below JSON functions in your `SessionContext`.
* [x] `json_as_text(json: str, *keys: str | int) -> str` - Get any value from a JSON string by its "path", represented as a string (used for the `->>` operator)
* [x] `json_length(json: str, *keys: str | int) -> int` - get the length of a JSON string or array

- [x] `->` operator - alias for `json_get`
- [x] `->>` operator - alias for `json_as_text`
- [x] `?` operator - alias for `json_contains`

### Notes
Cast expressions with `json_get` are rewritten to the appropriate method, e.g.

```sql
Expand Down
Loading