Adding Questions

Creating a Question

In Publisher, select the desired collection in the Collections tab in the sidebar. Click on the Sharing tab in the Collection and scroll down to the Questions section below the Download section. Click on "New Question" to start defining a new query.

Defining the Question

Fill in the Question Name and Description.

The description tells the user what type of query they are running.

Creating Your Query

The query will allow you to join tables from your collection, retrieve data, and apply filters using variables. Tables and their schema will be displayed in the left sidebar.

You may notice a default SQL statement in the query window. Remove the default SQL and replace it with your SQL statement for the question.

In the SQL editor, write a SQL query that pulls data from the necessary tables. Use JOIN to link related tables as needed.

Defining and Configuring Variables

The sidebar to the right of your Query window should automatically populate with new variables.

If this does not occur, please edit the SQL query to retype any variables in {{ }} format.

Using Variables in SQL

Define variables in the WHERE clause to make your query dynamic. For example:

Unset
SELECT *
FROM subject_metadata s
INNER JOIN enterotypes e
ON s.sample_name = e.sample_name
WHERE s.sex = {{sex}}

Here, {{sex}} is a variable that will be entered by the researcher when they run the query.

Configuring Variables

In the Variables panel on the right, create and configure the variables used in your SQL query.

• Name: The identifier for the variable matching the SQL query (e.g. sex).

• Label: The display name that researchers will see in Explorer when entering values.

• Type: Data type of the field (e.g. boolean, decimal, datetime, integer, string).

• Input Type: Specify the type of input (e.g. text, dropdown).

• Default Value (optional): Specify the default value of the variable that gets applied to the SQL.

• Description (optional): Add a description to guide researchers on how to use this variable.

Once this is filled in, you can test your query.

Testing Your Query

Click the "Test Query" button above the query window.

• If the results window displays an error message: Please double-check the SQL statement and the variables in the sidebar to resolve any issues. If the errors persist, copy the error message or take a screenshot and contact DNAstack for support.

• If the results window shows no errors: Click "Save" to preserve your work, even if the query is incomplete. You can always edit the question later to continue building or refining the query.

Note: If you do not save the question and an unexpected issue or session timeout occurs, you may lose all the progress made. Saving frequently is a best practice to avoid this.

Sharing Your Question to the Network

Once the question is tested and saved, navigate to the Sharing tab of your collection and scroll down to the Questions section.

In the Access Policy dropdown, admins can select from a variety of access permissions:

“Public” allows any researcher who accesses your Network to ask the question.

“Registered” only permits other researchers within your Network who have created accounts to ask the question.

Alternatively, admins may also select from any additional Access Policies that were created in your Network.

Once your access policy is selected, click “Save.”

Confirming Implementation

To confirm that the question has been successfully applied to your collection, perform the following steps:

1. Go to your Explorer site (e.g. neuroscience.ai)
2. Click the collection card representing your collection

3. Confirm that a new tab with the previously defined name for the question has been added to your collection.

4. Click on the tab, add inputs, and submit the question.