clickhouse-local: SQL queries over local and remote files

clickhouse-local is a ClickHouse tool and utility documented under the project's concepts section. It is designed for processing data without a server, so SQL can be run against files directly on a machine. The ClickHouse documentation includes guidance on when to use clickhouse-local as opposed to running ClickHouse as a database server; for the server route, the documentation points to the Quick Start instead. On the data warehousing use-case page, ClickHouse describes clickhouse-local as a powerful and portable tool to query, convert and transform data on a local machine.

• Part of the ClickHouse tools and utilities set
• Runs SQL without a ClickHouse server
• Documented alongside a "when to use clickhouse-local vs. ClickHouse" comparison

Queries are issued with the local subcommand of the ClickHouse binary, for example ./clickhouse local -q "SELECT * FROM 'reviews.tsv'". Files can be referenced directly by name or through the file() table function, with an optional format argument, and DESCRIBE returns the inferred column names and types. Glob patterns such as 'reviews*.jsonl', 'review_?.csv' and 'review_{1..3}.csv' allow several files to be read as one table. Aggregate and domain-specific functions can be applied in the same statement, as in queries using argMax and max over a TSV file.

• Direct file references and the file() table function
• DESCRIBE for schema inference
• Wildcard, single-character and range globs across multiple files

Beyond local files, clickhouse-local reads data over HTTP and from object storage. The documentation shows a CSV read straight from an HTTPS URL with LIMIT, and counts over Parquet files in S3 using both an s3:// path and the s3() table function. DESCRIBE works against remote Parquet in the same way as local files, and grouped aggregations such as counts and average prices per town and district can be run against a Parquet file in AWS S3, including bar() output for inline charts.

• Query a Parquet file with SQL from AWS S3
• s3() table function and s3:// paths
• CSV read directly from an HTTPS URL

clickhouse-local supports format conversions, and its usage options cover the input and output sides of a query. Input data structure is given with -S/--structure, the input format with --input-format (TSV by default) and the data path with -F/--file, which defaults to stdin. Queries come from -q/--query with semicolon delimiters or from --queries-file, with --multiquery/-n for multiple statements; output goes to a table named by -N/--table and is formatted with -f/--format or --output-format, also TSV by default. The documentation also records LS and CLEAR commands.

• -S, --structure for input table structure
• --input-format and -f/--output-format, TSV by default
• -F/--file, defaulting to stdin
• -q/--query, --queries-file and --multiquery/-n
• -N/--table for the output table name
• LS and CLEAR commands

clickhouse-local is obtained by downloading the standard ClickHouse binary with the command curl https://clickhouse.com/ | sh, and that binary can run the full range of ClickHouse tools and utilities. Configuration files are resolved from a documented list of locations, beginning with any path passed via --config-file. The search then covers ./config.xml, ./clickhouse-local.xml or ./clickhouse-local.yaml, the equivalents under ~/.clickhouse-local/, and files under /etc/clickhouse-local/ in XML or YAML form.

• Download command: curl https://clickhouse.com/ | sh
• --config-file path takes precedence
• Local ./config.xml and ./clickhouse-local.xml or .yaml
• ~/.clickhouse-local/config.xml or config.yaml
• /etc/clickhouse-local/config.xml or config.yaml

clickhouse-local sits within ClickHouse's broader support for analysing data in many formats. The data warehousing page states that ClickHouse provides support for more than 70 file formats, from Parquet to JSON, CSV and TSV, and positions clickhouse-local as the component covering local files. Users who instead need a running database server are directed to the ClickHouse Quick Start.

• Support for 70+ file formats across ClickHouse
• Covers the local-file side of data analysis
• Server deployments handled by ClickHouse itself