Quickstart

The easiest way to run Bunny is by using the provided Bunny Image command line interface to query an OMOP CDM database, without needing an upstream Task API.

This guide will help you quickly set up a local OMOP CDM database and run a query against it.

Prerequisites

Docker

Run a query

Get the Demo Compose file

Download the sample Bunny Demo Compose file by running the command:

curl -O https://raw.githubusercontent.com/Health-Informatics-UoN/hutch/refs/heads/main/samples/Bunny/bunny-demo.compose.yml

Or manually saving it to a file bunny-demo.compose.yml

Run the Compose file

This will start the database, initialise it with a synthetic OMOP CDM dataset, and run a query against it.

docker compose -f bunny-demo.compose.yml run --entrypoint uv bunny run bunny --body tests/queries/availability.json

This will take a minute or so to download the images and start the containers.

The query file is a JSON file that contains the query to run, which is a simple cohort definition, querying the Person table for 8507.

availability.json

{
  "task_id": "job-2023-01-13-14: 20: 38-project",
  "project": "project_id",
  "owner": "user1",
  "cohort": {
    "groups": [
      {
        "rules": [
          {
            "varname": "OMOP",
            "varcat": "Person",
            "type": "TEXT",
            "oper": "=",
            "value": "8507"
          }
        ],
        "rules_oper": "AND"
      }
    ],
    "groups_oper": "OR"
  },
  "collection": "collection_id",
  "protocol_version": "v2",
  "char_salt": "salt",
  "uuid": "unique_id"
}

🎉

Congratulations on your first Bunny query!

View the results

You should see output like the following:

{
  "status": "ok",
  "protocolVersion": "v2",
  "uuid": "unique_id",
  "queryResult": {
    "count": 44,
    "datasetCount": 0,
    "files": []
  },
  "message": "",
  "collection_id": "collection_id"
}

That contains the results of the query, which was 44.

Clean up

docker compose -f bunny-demo.compose.yml down

This will stop the database and remove the containers.

To remove the images, run:

docker rmi -f ghcr.io/health-informatics-uon/omop-lite:latest ghcr.io/health-informatics-uon/hutch/bunny:edge

Next Steps

To connect your Bunny to a upstream Task API, read the deployment guide.

Bunny Configuration