NOTE: For those deploying this database, Postgres does not by default use UTF-8, however it is required for the jsonb format used in some columns to always work. This stackoverflow post describes how to do it for Amazon RDS. This section of the docs states how to do it in general, i.e.:
initdb -E UTF8
.
This directory contains files related to the benchmark database.
To create a ‘machine.json’ file that will uniquely identify a computer for benchmark submission, run the provided shell script and fill in the prompts to identify the GPU.
NOTE: this does not work on VMs or Windows.
./make_machine_json.sh
Submit the machine details via http using the command
NOTE: This will only work if we have selected graphql as a client and have it running in production or if during development you have run
docker-compose up
to create and run both a database Docker container and graphql client Docker container.
./graphql_submit.sh machine machine.json localhost:5000/graphql
or submit after starting up the psql client from this directory, using
\set content `cat machine.json` SELECT ingest_machine_view(:'content'::jsonb);
NOTE: If you don't have a “machine.json” file generated, use the example file “examples/machine.json” instead.
There is a file named “[.env][.env]” in this directory that is used by docker-compose
to set up the postgres user and password for the local containers. Currently the name and password are both benchmark
. This will be the password for the psql client as well.
The Postgres Alpine image runs any added ‘*.sql’ and ‘*.sh’ scripts placed in ‘/docker-entrypoint-initdb.d/’ during its startup script, so the local database will be set up automatically once the container is running.
To start the containers, be sure to have Docker installed, and then run the following from this directory (arrow/dev/benchmarking).
docker-compose up
This will start a process that will show logs from both the running Postgres container and the running GraphQL container. To stop the running containers gracefully, background the process and run
docker-compose down fg # To re-foreground the backgrounded process while it exits
You will still have the container images “benchmarking_pg”, “graphile/postgraphile”, and “postgres:11-alpine” on your computer. You should keep them if you want to run this again. If you don't, then remove them with the command:
docker rmi benchmarking_pg postgres:11-alpine graphile/postgraphile
The psql
shell client is bundled with the PostgreSQL core distribution available from the Postgres download page. Using the PG_USER
defined in the .env
file (currently “benchmark”), the command to connect to the container is:
psql -h localhost -p 5432 -U benchmark
There is an example script in examples/example.sql that runs some queries against the database. To run it in the psql client, type the following in the psql command-line interface:
\i examples/example.sql
An example CSV file for bulk ingestion is in examples/benchmark_run_example.csv. The columns are listed in the same order as they are defined, to avoid having to explicitly name every column in ingestion. The “id” column is left empty and will be automatically assigned on insert.
To ingest the example CSV file from the command line, use the command below:
CSV='examples/benchmark_run_example.csv' && \ psql -U benchmark -h localhost -p 5432 \ -c "\copy benchmark_run_view FROM '${CSV}' WITH (FORMAT csv, HEADER);"
To ingest the example JSON file using the psql client, use the command below.
\set content `cat examples/benchmark_example.json` SELECT ingest_benchmark_view(:'content'::jsonb);
This section requires an actual HTTP client to be up, either for the production database or via the testing setup. (See the local testing section for how to set it up).
The ‘graphile/postgraphile’ container provides an HTTP interface to the database via two url routes:
--watch
flag on the command line. Not recommended for production.)The script graphql_submit.sh simplifies submission to the database via curl. Examples:
./graphql_submit.sh benchmarks examples/benchmark_example.json ./graphql_submit.sh runs examples/benchmark_run_example.json
The output of the query is a JSON object that is hard to read on the command line. Here is an example query in the shell:
curl -X POST \ -H "Content-Type: application/json" \ --data '{"query": "{projectDetails{ projectName }}"}' \ localhost:5000/graphql
which (if you have previously run the “examples.sql” command) yields
{"data":{"projectDetails":{"projectName":"Apache Arrow"}}}
Here is an example query using Python:
import json import requests uri = "http://localhost:5000/graphql" query = json.load(open("examples/graphql_query_environment_view.json")) response = requests.post(uri, json=query) message = "{benchmarkLanguage}: {languageImplementationVersion}, {dependencies}" for row in response.json()['data']['allEnvironmentViews']['edges']: print(message.format(**row['node'])) # result: # # Python: CPython 2.7, {"six":"","numpy":"1.14","other_lib":"1.0"} # Python: CPython 2.7, {"six":"","numpy":"1.15","other_lib":"1.0"} # Python: CPython 3.6, {"boost":"1.42","numpy":"1.15"}
(work in progress).
NOTE: For those deploying this database, Postgres does not by default use UTF-8, however it is required for the jsonb format used in some columns to always work. This stackoverflow post describes how to do it for Amazon RDS. This section of the docs states how to do it in general, i.e.:
initdb -E UTF8
.
'have single quotes'
'{"have", "curly", "braces"}'::text[]
or '{1, 2, 3}'::integer[]
'{"has":"this", "format":42}'::jsonb
[1, 2, 3]
) and do not have to use the above string formats.x IS NOT DISTINCT FROM y
rather than x = y
To recreate the data model documentation, (1) install the psql client (sorry you need to download the whole thing), (2) start the docker container using docker-compose up
, (3) and then run these scripts:
./make_dotfile.sh ./make_data_model_rst.sh