Please refer to our official documentation for more detailed information on how to use the query tool.
The query tool is hosted at https://query.neurobagel.org/ and interfaces with Neurobagel federation API.
To run the query tool locally, you have two options:
but before proceeding with either you need to set the environment variables.
Environment variable | Type | Required | Default value if not set | Example |
---|---|---|---|---|
NB_API_QUERY_URL | string | Yes | - | https://federate.neurobagel.org/ |
NB_IS_FEDERATION_API | boolean | No | true | true |
NB_ENABLE_AUTH | boolean | no | false | false |
NB_QUERY_CLIENT_ID | string | Yes (if NB_ENABLE_AUTH is set to true) | - | 46923719231972-dhsahgasl3123.apps.googleusercontent.com |
NB_API_QUERY_URL
You'll need to set the NB_API_QUERY_URL
environment variable required to run the query tool. NB_API_QUERY_URL
is the Neurobagel API URL that the query tool uses to send requests to for results.
NB_IS_FEDERATION_API
If the API you'd like to send queries to is not a federation api, you need to set the NB_IS_FEDERATION_API
to false
as it is true
by default.
NB_ENABLE_AUTH
If the API you'd like to send queries to requires authentication, you need to set NB_ENABLE_AUTH
to true
as it is false
by default. This will enable authentication flow of the app.
NB_QUERY_CLIENT_ID
If the NB_ENABLE_AUTH
is set to true
(it is false
by default), you need to provide a valid client ID for the authentication.
At the moment, query tool uses Google for authentication, so you need to obtain a client ID from Google developer console. See documentation for more information.
To set environment variables, create a .env
file in the root directory and add the environment variables there. If you're running a neurobagel node-API locally on your machine (following the instructions here), your .env
file would look something like this:
NB_API_QUERY_URL=http://localhost:8000/
NB_IS_FEDERATION_API=false # For node API
if you're using the remote (in this example federation) api, your .env
file would look something like this:
NB_API_QUERY_URL=https://federate.neurobagel.org/
if you're using a federation api with authentication, your .env
file would look something like this:
NB_API_QUERY_URL=https://federate.neurobagel.org/
NB_ENABLE_AUTH=true
NB_QUERY_CLIENT_ID=46923719231972-dhsahgasl3123.apps.googleusercontent.com
:warning: The protocol matters here.
If you wish to use the Neurobagel remote API, ensure your NB_API_QUERY_URL
uses https
instead of http
.
To obtain the query tool docker image, simply run the following command in your terminal:
docker pull neurobagel/query_tool:latest
This Docker image includes the latest release of the query tool and a minimal http server to serve the static tool.
To launch the query tool Docker container and pass in the .env
file you have created, simply run
docker run -p 5173:5173 --env-file=.env neurobagel/query_tool:latest
Then you can access the query tool at http://localhost:5173
Note: the query tool is listening on port 5173
inside the docker container,
replace port 5173
by the port you would like to expose to the host.
For example if you'd like to run the tool on port 8000
of your machine you can run the following command:
docker run -p 8000:5173 --env-file=.env neurobagel/query_tool:latest
To install the query tool directly, you'll need node package manager (npm) and Node.js. You can find the instructions on installing npm and node in the official documentation.
Once you have npm and node installed, you'll need to install the dependencies outlined in the package.json file. You can do so by running the following command:
npm install
To launch the tool in developer mode run the following command:
npm run dev
You can also build and then run the tool from (production) build of the application by running the following command:
npm run build && npm run preview
You can verify the tool is running by watching for the` info messages from Vite regarding environment, rendering, and what port the tool is running on in your terminal.
Having installed the dependencies, run the following command to enable husky pre-commit
and post-merge
hooks:
npx husky install
To define a cohort, set your inclusion criteria using the following:
Once you've defined your criteria, submit them as a query and the query tool will display the results.\ The query tool offers two different TSV files for results:
The output files can be joined using DatasetID
as key.
You can refer to the neurobagel documentation to see what the outputs of the query tool look like and how they are structured. You can also download the raw example output files here.
The query tool utilizes Cypress framework for testing.
To run the tests execute the following command:
npx cypress open
The query tool is released under the terms of the MIT License