|
| 1 | +--- |
| 2 | +title: Command line interface |
| 3 | +--- |
| 4 | + |
| 5 | +The `ggsql` command line interface lets you execute queries and validate syntax directly from the terminal. While it may not be the most ergonomic way to interact directly with ggsql, it is useful for scripting, automation, and building tools around ggsql. |
| 6 | + |
| 7 | +## Installation |
| 8 | + |
| 9 | +Install the ggsql CLI on your system using the standard [installation instructions](../installation.html). |
| 10 | + |
| 11 | +## Executing a query |
| 12 | + |
| 13 | +You can execute a ggsql query from a string with `ggsql exec`: |
| 14 | + |
| 15 | +```bash |
| 16 | +ggsql exec "VISUALISE species AS fill FROM ggsql:penguins DRAW bar" |
| 17 | +``` |
| 18 | + |
| 19 | +Or run a `.gsql` file: |
| 20 | + |
| 21 | +```bash |
| 22 | +ggsql run my_query.gsql |
| 23 | +``` |
| 24 | + |
| 25 | +In both cases, output is written to `stdout` as a Vega-Lite JSON spec. You can redirect it to a file: |
| 26 | + |
| 27 | +```bash |
| 28 | +ggsql run my_query.gsql > chart.vl.json |
| 29 | +``` |
| 30 | + |
| 31 | +Such files can be rendered as images using tools that work with Vega-Lite specs, such as the [Online Vega Editor](https://vega.github.io/editor/) or [vl-convert](https://github.com/vega/vl-convert) command line tool. For example, |
| 32 | + |
| 33 | +```bash |
| 34 | +vl-convert vl2png -i chart.vl.json -o chart.png |
| 35 | +``` |
| 36 | + |
| 37 | +A standard SQL query can also be provided to ggsql. If the query returns a table, the resulting values will be written to `stdout`. |
| 38 | + |
| 39 | +## Validating a query |
| 40 | + |
| 41 | +If you only want to check that a query is syntactically valid without executing it, use `ggsql validate`: |
| 42 | + |
| 43 | +```bash |
| 44 | +$ ggsql validate "VISUALISE x, y FROM table DRAW point" |
| 45 | +✓ Query syntax is valid |
| 46 | +``` |
| 47 | + |
| 48 | +## Database connections |
| 49 | + |
| 50 | +Both `ggsql exec` and `ggsql run` accept a `--reader` flag that can be used to specify a connection string to be used when executing the query. If not provided, ggsql will use an empty in-memory duckdb connection, equivalent to `--reader duckdb://memory`. |
| 51 | + |
| 52 | +```bash |
| 53 | +$ ggsql exec --reader sqlite://sample/ggsql_test.sqlite \ |
| 54 | + "SELECT * FROM test_table LIMIT 3" |
| 55 | +col_a, col_b, col_c |
| 56 | +215.87, 75.11, delta |
| 57 | +418.78, 71.75, delta |
| 58 | +495.75, 12.55, delta |
| 59 | + |
| 60 | +$ ggsql exec --reader odbc://DSN=ggsql-pg-test \ |
| 61 | + "SELECT * FROM test_table LIMIT 3" |
| 62 | +col_a, col_b, col_c |
| 63 | +319.34, 91.45, gamma |
| 64 | +299.08, 49.36, epsilon |
| 65 | +12.5, 29.48, gamma |
| 66 | +``` |
| 67 | + |
| 68 | +## Documentation |
| 69 | + |
| 70 | +The ggsql CLI has built-in documentation for ggsql syntax and usage. Run `ggsql docs` for an overview of available documentation topics, and `ggsql docs [topic]` to read about a specific topic. |
| 71 | + |
| 72 | +```bash |
| 73 | +$ ggsql docs draw |
| 74 | +DRAW is perhaps the most important clause in ggsql as it defines a layer in your |
| 75 | +visualisation. A layer is a single instance of a visual representation of a dataset. |
| 76 | +[...] |
| 77 | +``` |
| 78 | + |
| 79 | +A ggsql skill, a usage guide intended for AI assistants and humans, can also be output using the `ggsql skill` command. |
| 80 | + |
| 81 | +```bash |
| 82 | +$ ggsql skill |
| 83 | + ggsql Query Writer |
| 84 | +ggsql is a SQL extension for declarative data visualization based on |
| 85 | +Grammar of Graphics principles. |
| 86 | +[...] |
| 87 | +``` |
0 commit comments