Datasets¶
create¶
HTTP Request
POST https://api.solvebio.com/v2/datasets
Parameters
This request does not accept URL parameters.
Authorization
This request requires an authorized user with permission to create new datasets.
Request Body
In the request body, provide a single Dataset resource.
Property | Value | Description |
---|---|---|
name | string | The unique name within the vault for this dataset. |
vault_id | integer | The vault version in which to create the dataset. |
vault_parent_object_id | integer | The folder ID in which to create the dataset. Use 'null' to place at '/'. |
fields | Dataset Fields | A list of dataset field objects. |
metadata | object | A dictionary of key/value pairs. |
tags | string | A list of strings to organize the dataset. |
capacity | string | (Optional) The dataset capacity level (small, medium, or large). |
storage_class | string | (Optional) The dataset storage class |
Response
The response contains a single Dataset resource.
delete¶
HTTP Request
DELETE https://api.solvebio.com/v2/datasets/{DATASET_ID}
Parameters
This request does not accept URL parameters.
Authorization
This request requires an authorized user with permission to modify the target dataset.
Request Body
Do not supply a request body with this method.
Response
The response returns "HTTP 200 OK" when successful.
get¶
HTTP Request
GET https://api.solvebio.com/v2/datasets/{DATASET_ID}
Parameters
This request does not accept URL parameters.
Authorization
This request requires an authorized user with permission to view the target dataset.
Request Body
Do not supply a request body with this method.
Response
The response contains a Dataset resource.
query¶
HTTP Request
POST https://api.solvebio.com/v2/datasets/{DATASET_ID}/data
Parameters
This request does not accept URL parameters.
Authorization
This request requires an authorized user with permission to query the target dataset.
Request Body
The request body should contain valid query parameters:
Property | Value | Description |
---|---|---|
filters | objects | A valid filter object (see below). |
facets | objects | A valid facets object (see below). |
fields | string | A list of fields to include in the results. |
exclude_fields | string | A list of fields to exclude in the results. |
ordering | string | A list of fields to order results by. |
query | string | A valid query string. |
limit | integer | The number of results to return per-page. |
offset | integer | The record offset in the result-set. |
Filters & Facets
SolveBio's Python language bindings take care of generating filter syntax automatically.
You can filter datasets on any field using the following filter syntax pattern:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 | # General pattern { "filters": [ { "{BOOLEAN_OPERATOR}": [ ["{FIELD}", "{VALUE}"], ["{FIELD}__{ACTION}", "{VALUE}"] ] } ] } # Example: Simple equality filter { "filters": [ ["{FIELD}", "{VALUE}"] ] } # Example: Simple ORed equality filters { "filters": [ { "or": [ ["{FIELD}", "{VALUE1}"], ["{FIELD}", "{VALUE2}"] ] } ] } |
Query filters use a nested syntax, where:
{BOOLEAN_OPERATOR}
is one ofand
,or
, ornot
.{FIELD}
is a documented field name in the dataset.{ACTION}
is a valid field action (see below).{VALUE}
can be a string, numeric, or list value.
By default, a {FIELD}
with no attached {ACTION}
implies the "equal to" operator. Valid actions include:
Action | Description |
---|---|
(none) | Field is equal to value. If the field's value is a list, this will match values within the list, not the list as a whole. |
exact | Field is an exact match to value. Useful for longer string and text fields. |
in | Field is "one of" value, where value is a list. (similar to Python's in operator). |
range | Field is a number within two within two values. Ranges are inclusive (fully-closed). |
gt | Field is a number greater than value. |
lt | Field is a number less than value. |
gte | Field is a number greater than or equal to value. |
lte | Field is a number less than or equal to value. |
contains | Field contains this string value. |
regexp | Field value matches this regular expression. |
Some filter actions (range
, gt
, lt
, gte
, lte
) may only be used on numeric and date fields.
Full-text fields automatically use the contains
filter action instead. The contains
filter action acts like a typical search would. Results are automatically ordered by relevance based on your search terms.
See the Querying Data Guide section for more examples.
Response
The dataset query response has the following structure:
Property | Value | Description |
---|---|---|
dataset | string | The name of the dataset. |
dataset_id | integer | The ID of the dataset. |
facets | objects | Facet results (if a facets are requested). |
offset | integer | The current offset within the whole result-set. |
results | objects | A list of dataset records. |
took | intger | Time to retrieve the records, in miliseconds. |
total | integer | The total number of records in the result-set. |
batch_query¶
HTTP Request
POST https://api.solvebio.com/v1/batch_query
Parameters
This request does not accept URL parameters.
Authorization
This request requires an authorized user with permission to query all the datasets provided.
Request Body
The request body should contain a list of one or more dataset queries:
Response
The response contains a list of dataset query responses (see above) with status codes in the same order as specified in the request.