This directory contains tools for running performance benchmarks on the BigQuery JDBC driver.

• run_perf.py: A Python script that orchestrates running the tests, collecting metrics, and displaying results in a table view.
• Makefile: A convenience wrapper to run common test configurations.

• Python 3
• Java 11 or later
• BigQuery JDBC driver JAR(s) to test.

Note: The Java client (JDBCClient) is automatically compiled when using the Makefile.

The easiest way to run tests is using the provided Makefile. It defines targets for REST API and High Throughput API (HTAPI) modes.

The Makefile uses the following defaults which can be overridden:

• ITERATIONS: 5
• ROWS: 1000 (default, used if no query/query_file is specified)
• COLS: 5 (default, used if no query/query_file is specified)
• QUERY: Optional custom query to run
• QUERY_FILE: Optional path to a SQL file containing the query to run
• JAR1: ../../drivers/google-cloud-bigquery-jdbc-0.9.0-all.jar
• PROJECT_ID: bigquery-devtools-drivers
• CREDENTIALS: Value of $GOOGLE_APPLICATION_CREDENTIALS

make run-rest

make run-rest ROWS=50000 COLS=10

make run-htapi ITERATIONS=3 QUERY="SELECT * FROM my_dataset.my_table LIMIT 50000"

To compare two different driver JARs, provide JAR2 (and optionally CLASS2 if different from default):

make run-rest JAR1=path/to/driver1.jar JAR2=path/to/driver2.jar

For more control, you can run run_perf.py directly.

• --url: (Required) JDBC connection URL.
• --jar1: (Required) Path to the first driver JAR.
• --jar2: Path to the second driver JAR (optional, for comparison).
• --class1: Class name for the first driver (default: com.google.cloud.bigquery.jdbc.BigQueryDriver).
• --class2: Class name for the second driver (default: com.google.cloud.bigquery.jdbc.BigQueryDriver).
• -n, --iterations: Number of iterations to run (default: 5).
• --query: The query to run.
• --query-file: Path to a SQL file containing the query to run.
• --generate-rows: Number of rows to generate (default: 0, used if no query/query_file is specified).
• --generate-cols: Number of columns to generate (default: 5).
• --output-md: Append results as a markdown table to this file.
• --filter-metrics: Comma-separated list of metrics to include in the markdown table.

python3 run_perf.py --url "jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-project;OAuthType=3" --jar1 path/to/driver.jar --query "SELECT * FROM my_dataset.my_table LIMIT 1000" -n 3

python3 run_perf.py --url "jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-project;OAuthType=3" --jar1 path/to/driver.jar --generate-rows 1000 -n 3

python3 run_perf.py --url "jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;ProjectId=my-project;OAuthType=3" --jar1 path/to/driver1.jar --jar2 path/to/driver2.jar --query "SELECT * FROM my_dataset.my_table LIMIT 1000"