The fluvio table-format command
Table Format is used to customize the behavior of the Fluvio consumer output type [full-table].
With table-format, you can control the column labels, column ordering and control which keys are primary for displaying your live event data as row updates.
fluvio table-format
Install Fluvio plugins
The Fluvio CLI considers any executable with the prefix `fluvio-` to be a CLI plugin. For example, an executable named `fluvio-foo` in your PATH may be invoked by running `fluvio foo`.
This command allows you to install plugins from Fluvio's package registry.
Usage: fluvio install [OPTIONS] [PACKAGE]
Arguments:
[PACKAGE]
The ID of a package to install, e.g. "fluvio/fluvio-cloud"
Options:
--develop
Install the latest prerelease rather than the latest release
If the package ID contains a version (e.g. `fluvio/fluvio:0.6.0`), this is ignored
--hub
When this flag is provided, use the hub. Dev-only
--use-hub-defaults
Use local hub defaults. Implied if INFINYON_HUB_REMOTE or FLUVIO_CLOUD_PROFILE env vars are set - Dev-only
--channel <CHANNEL>
When this flag is provided, use the hub. Dev-only
--target <TARGET>
override default target arch determination
-h, --help
Print help (see a summary with '-h')
This is the schema for the Table Format yaml config used by fluvio table-format create
You only need to give your Table Format a name, and an input format (currently only JSON is supported)
TableFormat Config schema
This is a definition of the TableFormat config schema. Below are the descriptions of each field of the config file.
Check out the examples section below to see a few different config files and their resulting table views.
type: object
required: ["name"]
properties:
name:
type: string
minimum: 1
maximum: 100
inputFormat:
type: string
enum:
- JSON
columns:
type: array
items:
type: object
properties:
headerLabel:
type: string
keyPath:
type: string
primaryKey:
type: boolean
Field descriptions
name
Required
This is the name of your Table Format. You'll see this name when you run fluvio table-format list, and you'll use this name with fluvio consume topic-name --table-format <name>
inputFormat
Required
The only supported option for this field is "JSON"
columns
optional array - The default column display will be the top-level keys (ordered alphabetically).
Each element references a key from input json object.
The ordering of each element is important, as it will be the order columns will be rendered.
keyPath
This is the only required column field. This should be a top-level key. If the key path doesn't exist, the column will print with no data.
headerLabel
optional - default uses key name. Override the label of the column.
primaryKey
optional - default false. If specified to true, rendering updates to the table will compare the values of primary keys to define a set. When new data matches an existing set, it's row will be updated. Otherwise it will append a new row to the table.
Examples
For the following examples, we'll start off with our topic data arriving in this order.
{"key1":"a","key2":"1","key3":"Alice","id":123}
{"key1":"b","key2":"2","key3":"Bob","id":456}
{"key1":"c","key2":"3","key3":"Carol","id":789}
[{"key1":"x","key2":"10","key3":"Alice","id":123},{"key1":"y","key2":"20","key3":"Bob","id":456},{"key1":"c","key2":"30","key3":"Carol","id":789}]
The expected shape of the data is either:
- a JSON object
- a JSON array of objects
Example 0
No table-format
Using the [full-table] output without using a table-format print each key into a column in alphabetical order from left to right.
$ fluvio consume event-data -B --output full-table
Output:
┌('c' to clear table | 'q' or ESC to exit) | Items: 6─────────────────┐
│id key1 key2 key3 │
│123 a 1 Alice │
│456 b 2 Bob │
│789 c 3 Carol │
│123 x 10 Alice │
│456 y 20 Bob │
│789 c 30 Carol │
└─────────────────────────────────────────────────────────────────────┘
Example 1
Display a subset of data
In this example, we only want to display data for only 2 of the keys. The ordering of the columns will be key1 first, then key2.
Config:
# exampleformat1.yaml
name: "exampleformat1"
inputFormat: "JSON"
columns:
- keyPath: "key1"
- keyPath: "key2"
Create the table-format:
$ fluvio table-format create --config exampleformat1.yaml
Display your table:
$ fluvio consume event-data -B --output full-table --table-format exampleformat1
Output:
┌('c' to clear table | 'q' or ESC to exit) | Items: 6─────────────────┐
│key1 key2 │
│a 1 │
│b 2 │
│c 3 │
│x 10 │
│y 20 │
│c 30 │
└─────────────────────────────────────────────────────────────────────┘
Example 2
Reorder columns
In this example, we rearrange the order so that the columns will be ordered: id, key3, key1, key2
Config:
# exampleformat2.yaml
name: "exampleformat2"
inputFormat: "JSON"
columns:
- keyPath: "id"
- keyPath: "key3"
- keyPath: "key1"
- keyPath: "key2"
Create the table-format:
$ fluvio table-format create --config exampleformat2.yaml
Display your table:
$ fluvio consume event-data -B --output full-table --table-format exampleformat2
Output:
┌('c' to clear table | 'q' or ESC to exit) | Items: 6─────────────────┐
│id key3 key1 key2 │
│123 Alice a 1 │
│456 Bob b 2 │
│789 Carol c 3 │
│123 Alice x 10 │
│456 Bob y 20 │
│789 Carol c 30 │
└─────────────────────────────────────────────────────────────────────┘
Example 3
Rename columns
In this example, we're rearranging the order of the columns, and changing the column header to something more meaningful for our data.
Config:
# exampleformat3.yaml
name: "exampleformat3"
inputFormat: "JSON"
columns:
- keyPath: "id"
headerLabel: "ID"
- keyPath: "key3"
headerLabel: "Name"
- keyPath: "key2"
headerLabel: "Number"
- keyPath: "key1"
headerLabel: "Letter"
Create the table-format:
$ fluvio table-format create --config exampleformat3.yaml
Display your table:
$ fluvio consume event-data -B --output full-table --table-format exampleformat3
Output:
┌('c' to clear table | 'q' or ESC to exit) | Items: 6─────────────────┐
│ID Name Number Letter │
│123 Alice 1 a │
│456 Bob 2 b │
│789 Carol 3 c │
│123 Alice 10 x │
│456 Bob 20 y │
│789 Carol 30 c │
└─────────────────────────────────────────────────────────────────────┘
Example 4: Choose primary key for row-updates
For event-sourced data, it may be beneficial to display the most up-to-date data by updating the row with current values. To do this, we select a primary key within the data.
When new data arrives, if the values at the primary key match, we replace the row with the more recent data.
Config:
# exampleformat4.yaml
name: "exampleformat4"
inputFormat: "JSON"
columns:
- keyPath: "id"
headerLabel: "ID"
primaryKey: true
- keyPath: "key3"
headerLabel: "Name"
- keyPath: "key2"
- keyPath: "key1"
Command:
$ fluvio table-format create --config exampleformat4.yaml
Display your table:
$ fluvio consume event-data -B --output full-table --table-format exampleformat4
Output:
┌('c' to clear table | 'q' or ESC to exit) | Items: 3─────────────────┐
│ID Name key2 key1 │
│123 Alice 10 x │
│456 Bob 20 y │
│789 Carol 30 c │
└─────────────────────────────────────────────────────────────────────┘
Consumer output table formatting
This document covers two of the the CLI Consumer's output types.
--output tablewhich is a simple formatted table--output full-tablewhich is a text-based user interface, with features such as live row-based updates, and column customization via [table-format]
To demonstrate the table output, we're going to use the following input
Example initial topic input
{"key1":"a","key2":"1","key3":"Alice","id":123}
{"key1":"b","key2":"2","key3":"Bob","id":456}
{"key1":"c","key2":"3","key3":"Carol","id":789}
[{"key1":"x","key2":"10","key3":"Alice","id":123},{"key1":"y","key2":"20","key3":"Bob","id":456},{"key1":"c","key2":"30","key3":"Carol","id":789}]
The expected shape of the data is either:
- a JSON object
- a JSON array of objects
table
By default the top-level object keys will be used as the column names, sorted by alphabetical order. For more customizability, please use the [full-table] output
Example command:
$ fluvio consume example-topic --output table -B
Example output:
id | key1 | key2 | key3
123 | a | 1 | Alice
456 | b | 2 | Bob
789 | c | 3 | Carol
123 | x | 10 | Alice
456 | y | 20 | Bob
789 | c | 30 | Carol
full-table
By default the top-level object keys will be used as the column names, sorted by alphabetical order.
Example command:
$ fluvio consume example-topic --output full-table -B
Example output:
┌('c' to clear table | 'q' or ESC to exit) | Items: 6─────────────────┐
│id key1 key2 key3 │
│123 a 1 Alice │
│456 b 2 Bob │
│789 c 3 Carol │
│123 x 10 Alice │
│456 y 20 Bob │
│789 c 30 Carol │
└─────────────────────────────────────────────────────────────────────┘
You can scroll with
up/downarrow keys or the mouse scroll wheel to move one row at a timePage up/Page downto move 5 rows up/down at a timeHometo move to the top of the tableEndto move to the bottom of the tablecto clear the table stateqorESCto exit the table
Customize the full-table table
You may have json data that isn't most effectively displayed with the keys ordered alphabetically. Or your data is event sourced, and you only want to see the most recent data organized by one or more primary keys.
In that case, to customize the full-table output, you can provide the name of your table-format
fluvio consume <topic-name> --output full-table --table-format <table-format name>