Skip to content

Commit

Permalink
Format NULL consistently
Browse files Browse the repository at this point in the history
  • Loading branch information
@szarnyasg
szarnyasg committed Nov 27, 2024
1 parent bdaccb0 commit 8622204
Show file tree
Hide file tree
Showing 24 changed files with 203 additions and 172 deletions.
8 changes: 5 additions & 3 deletions docs/api/c/vector.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ For primitive types, the underlying array can be obtained using the `duckdb_vect
| DUCKDB_TYPE_TIME_TZ | duckdb_time_tz |
| DUCKDB_TYPE_TIMESTAMP_TZ | duckdb_timestamp |

### Null Values
### `NULL` Values

Any value in a vector can be `NULL`. When a value is `NULL`, the values contained within the primary array at that index is undefined (and can be uninitialized). The validity mask is a bitmask consisting of `uint64_t` elements. For every `64` values in the vector, one `uint64_t` element exists (rounded up). The validity mask has its bit set to 1 if the value is valid, or set to 0 if the value is invalid (i.e .`NULL`).

Expand Down Expand Up @@ -439,9 +439,11 @@ The bit is set to 1 if the value is valid (i.e., not NULL) or 0 if the value is

Validity of a specific value can be obtained like this:

```c
idx_t entry_idx = row_idx / 64;
idx_t idx_in_entry = row_idx % 64;
bool is_valid = validity_mask[entry_idx] & (1 << idx_in_entry);
```

Alternatively, the (slower) duckdb_validity_row_is_valid function can be used.

Expand All @@ -458,7 +460,7 @@ Alternatively, the (slower) duckdb_validity_row_is_valid function can be used.

##### Return Value

The pointer to the validity mask, or NULL if no validity mask is present
The pointer to the validity mask, or `NULL` if no validity mask is present

<br>

Expand All @@ -467,7 +469,7 @@ The pointer to the validity mask, or NULL if no validity mask is present
Ensures the validity mask is writable by allocating it.

After this function is called, `duckdb_vector_get_validity` will ALWAYS return non-NULL.
This allows null values to be written to the vector, regardless of whether a validity mask was present before.
This allows `NULL` values to be written to the vector, regardless of whether a validity mask was present before.

##### Syntax

Expand Down
96 changes: 48 additions & 48 deletions docs/api/cli/dot_commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,54 +15,54 @@ Dot commands are available in the DuckDB CLI client. To use one of these command

| Command | Description |
|---|------|
| `.bail on|off` | Stop after hitting an error. Default: `off` |
| `.binary on|off` | Turn binary output on or off. Default: `off` |
| `.cd DIRECTORY` | Change the working directory to `DIRECTORY` |
| `.changes on|off` | Show number of rows changed by SQL |
| `.check GLOB` | Fail if output since .testcase does not match |
| `.columns` | Column-wise rendering of query results |
| `.constant ?COLOR?` | Sets the syntax highlighting color used for constant values |
| `.constantcode ?CODE?` | Sets the syntax highlighting terminal code used for constant values |
| `.databases` | List names and files of attached databases |
| `.echo on|off` | Turn command echo on or `off` |
| `.excel` | Display the output of next command in spreadsheet |
| `.exit ?CODE?` | Exit this program with return-code `CODE` |
| `.explain ?on|off|auto?` | Change the `EXPLAIN` formatting mode. Default: `auto` |
| `.fullschema ?--indent?` | Show schema and the content of `sqlite_stat` tables |
| `.headers on|off` | Turn display of headers on or `off` |
| `.help ?-all? ?PATTERN?` | Show help text for `PATTERN` |
| `.highlight [on|off]` | Toggle syntax highlighting in the shell `on`/`off` |
| `.import FILE TABLE` | Import data from `FILE` into `TABLE` |
| `.indexes ?TABLE?` | Show names of indexes |
| `.keyword ?COLOR?` | Sets the syntax highlighting color used for keywords |
| `.keywordcode ?CODE?` | Sets the syntax highlighting terminal code used for keywords |
| `.lint OPTIONS` | Report potential schema issues. |
| `.log FILE|off` | Turn logging on or off. `FILE` can be `stderr`/`stdout` |
| `.maxrows COUNT` | Sets the maximum number of rows for display. Only for [duckbox mode]({% link docs/api/cli/output_formats.md %}) |
| `.maxwidth COUNT` | Sets the maximum width in characters. 0 defaults to terminal width. Only for [duckbox mode]({% link docs/api/cli/output_formats.md %}) |
| `.mode MODE ?TABLE?` | Set [output mode]({% link docs/api/cli/output_formats.md %}) |
| `.multiline` | Set multi-line mode (default) |
| `.nullvalue STRING` | Use `STRING` in place of `NULL` values |
| `.once ?OPTIONS? ?FILE?` | Output for the next SQL command only to `FILE` |
| `.open ?OPTIONS? ?FILE?` | Close existing database and reopen `FILE` |
| `.output ?FILE?` | Send output to `FILE` or `stdout` if `FILE` is omitted |
| `.parameter CMD ...` | Manage SQL parameter bindings |
| `.print STRING...` | Print literal `STRING` |
| `.prompt MAIN CONTINUE` | Replace the standard prompts |
| `.quit` | Exit this program |
| `.read FILE` | Read input from `FILE` |
| `.rows` | Row-wise rendering of query results (default) |
| `.schema ?PATTERN?` | Show the `CREATE` statements matching `PATTERN` |
| `.separator COL ?ROW?` | Change the column and row separators |
| `.sha3sum ...` | Compute a SHA3 hash of database content |
| `.shell CMD ARGS...` | Run `CMD ARGS...` in a system shell |
| `.show` | Show the current values for various settings |
| `.singleline` | Set single-line mode |
| `.system CMD ARGS...` | Run `CMD ARGS...` in a system shell |
| `.tables ?TABLE?` | List names of tables [matching LIKE pattern]({% link docs/sql/functions/pattern_matching.md %}) `TABLE` |
| `.testcase NAME` | Begin redirecting output to `NAME` |
| `.timer on|off` | Turn SQL timer on or off |
| `.width NUM1 NUM2 ...` | Set minimum column widths for columnar output |
| `.bail on|off` | Stop after hitting an error. Default: `off` |
| `.binary on|off` | Turn binary output on or off. Default: `off` |
| `.cd DIRECTORY` | Change the working directory to `DIRECTORY` |
| `.changes on|off` | Show number of rows changed by SQL |
| `.check GLOB` | Fail if output since .testcase does not match |
| `.columns` | Column-wise rendering of query results |
| `.constant ?COLOR?` | Sets the syntax highlighting color used for constant values |
| `.constantcode ?CODE?` | Sets the syntax highlighting terminal code used for constant values |
| `.databases` | List names and files of attached databases |
| `.echo on|off` | Turn command echo on or `off` |
| `.excel` | Display the output of next command in spreadsheet |
| `.exit ?CODE?` | Exit this program with return-code `CODE` |
| `.explain ?on|off|auto?` | Change the `EXPLAIN` formatting mode. Default: `auto` |
| `.fullschema ?--indent?` | Show schema and the content of `sqlite_stat` tables |
| `.headers on|off` | Turn display of headers on or `off` |
| `.help ?-all? ?PATTERN?` | Show help text for `PATTERN` |
| `.highlight [on|off]` | Toggle syntax highlighting in the shell `on`/`off` |
| `.import FILE TABLE` | Import data from `FILE` into `TABLE` |
| `.indexes ?TABLE?` | Show names of indexes |
| `.keyword ?COLOR?` | Sets the syntax highlighting color used for keywords |
| `.keywordcode ?CODE?` | Sets the syntax highlighting terminal code used for keywords |
| `.lint OPTIONS` | Report potential schema issues. |
| `.log FILE|off` | Turn logging on or off. `FILE` can be `stderr`/`stdout` |
| `.maxrows COUNT` | Sets the maximum number of rows for display. Only for [duckbox mode]({% link docs/api/cli/output_formats.md %}) |
| `.maxwidth COUNT` | Sets the maximum width in characters. 0 defaults to terminal width. Only for [duckbox mode]({% link docs/api/cli/output_formats.md %}) |
| `.mode MODE ?TABLE?` | Set [output mode]({% link docs/api/cli/output_formats.md %}) |
| `.multiline` | Set multi-line mode (default) |
| `.nullvalue STRING` | Use `STRING` in place of `NULL` values |
| `.once ?OPTIONS? ?FILE?` | Output for the next SQL command only to `FILE` |
| `.open ?OPTIONS? ?FILE?` | Close existing database and reopen `FILE` |
| `.output ?FILE?` | Send output to `FILE` or `stdout` if `FILE` is omitted |
| `.parameter CMD ...` | Manage SQL parameter bindings |
| `.print STRING...` | Print literal `STRING` |
| `.prompt MAIN CONTINUE` | Replace the standard prompts |
| `.quit` | Exit this program |
| `.read FILE` | Read input from `FILE` |
| `.rows` | Row-wise rendering of query results (default) |
| `.schema ?PATTERN?` | Show the `CREATE` statements matching `PATTERN` |
| `.separator COL ?ROW?` | Change the column and row separators |
| `.sha3sum ...` | Compute a SHA3 hash of database content |
| `.shell CMD ARGS...` | Run `CMD ARGS...` in a system shell |
| `.show` | Show the current values for various settings |
| `.singleline` | Set single-line mode |
| `.system CMD ARGS...` | Run `CMD ARGS...` in a system shell |
| `.tables ?TABLE?` | List names of tables [matching LIKE pattern]({% link docs/sql/functions/pattern_matching.md %}) `TABLE` |
| `.testcase NAME` | Begin redirecting output to `NAME` |
| `.timer on|off` | Turn SQL timer on or off |
| `.width NUM1 NUM2 ...` | Set minimum column widths for columnar output |

## Using the `.help` Command

Expand Down
40 changes: 20 additions & 20 deletions docs/api/cli/output_formats.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,26 +10,26 @@ The `markdown` mode is particularly useful for building documentation and the `l

<div class="narrow_table"></div>

| Mode | Description |
|--------------|----------------------------------------------|
| `ascii` | Columns/rows delimited by 0x1F and 0x1E |
| `box` | Tables using unicode box-drawing characters |
| `csv` | Comma-separated values |
| `column` | Output in columns. (See .width) |
| `duckbox` | Tables with extensive features (default) |
| `html` | HTML `<table>` code |
| `insert` | SQL insert statements for TABLE |
| `json` | Results in a JSON array |
| `jsonlines` | Results in a NDJSON |
| `latex` | LaTeX tabular environment code |
| `line` | One value per line |
| `list` | Values delimited by "\|" |
| `markdown` | Markdown table format |
| `quote` | Escape answers as for SQL |
| `table` | ASCII-art table |
| `tabs` | Tab-separated values |
| `tcl` | TCL list elements |
| `trash` | No output |
| Mode | Description |
|--------------|---------------------------------------------|
| `ascii` | Columns/rows delimited by 0x1F and 0x1E |
| `box` | Tables using unicode box-drawing characters |
| `csv` | Comma-separated values |
| `column` | Output in columns. (See .width) |
| `duckbox` | Tables with extensive features (default) |
| `html` | HTML `<table>` code |
| `insert` | SQL insert statements for TABLE |
| `json` | Results in a JSON array |
| `jsonlines` | Results in a NDJSON |
| `latex` | LaTeX tabular environment code |
| `line` | One value per line |
| `list` | Values delimited by "\|" |
| `markdown` | Markdown table format |
| `quote` | Escape answers as for SQL |
| `table` | ASCII-art table |
| `tabs` | Tab-separated values |
| `tcl` | TCL list elements |
| `trash` | No output |

Use `.mode` directly to query the appearance currently in use.

Expand Down
Loading

0 comments on commit 8622204

Please sign in to comment.