chembl-get-bioactivities
chembl_get_bioactivitiesThe flagship compound↔target bioactivity bridge: measurements for a molecule (target deconvolution / selectivity), a target (lead finding), or both together (how potently one compound hits one target). Supply at least one of molecule_chembl_id (from chembl_search_molecules) or target_chembl_id (from chembl_search_targets) — supplying both narrows to that compound–target pair, supplying neither is an error. Filter by standard_type (IC50/Ki/EC50/…), minimum potency pchembl_value_min, assay_type, and organism. Not every measurement has a derivable pchembl_value, so potency_view picks which side of that split you get: the default "potency_ranked" returns the measurements that have one, most potent first (ChEMBL sorts the rest first otherwise, which is why they are not merged), and "null_potency" returns exactly the measurements that have none. totalCount is the honest full match count across both views either way. Mixing measurement types (IC50 vs Ki) is a scientific error — set standard_type to compare like with like. A popular target carries tens of thousands of rows: results spill to a DataCanvas table (call chembl_dataframe_describe for its columns, then chembl_dataframe_query for honest aggregates across the staged set), while an inline preview answers the immediate question. Each view stages its own table (bioactivities / bioactivities_null_potency), so running both against one canvas_id lets a UNION ALL rebuild the full set. The staged table is capped at CHEMBL_MAX_SPILL_ROWS; when the cap is hit, truncated is true and the table is a bounded slice, not the complete view. The inline rows are always capped at limit, so compare that against totalCount before treating them as the whole answer. Spilling the rest requires CANVAS_PROVIDER_TYPE=duckdb; without it the inline preview is all there is.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows in the inline preview. Defaults to the server default (25). The full set still spills to the canvas. | |
| organism | No | Restrict to a target organism, e.g. "Homo sapiens" (case-insensitive exact match). | |
| canvas_id | No | Optional canvas ID from a prior call to reuse the same canvas. Each potency_view re-stages its own table, so a second query of the SAME view REPLACES (overwrites) its prior rows — it does not append — while the other view's table is left intact, which is what lets both coexist on one canvas. Omit to mint a fresh canvas. | |
| assay_type | No | Restrict to an assay type code: "B" (binding), "F" (functional), "A" (ADMET), "T" (toxicity). | |
| potency_view | No | Which side of the pchembl_value presence split to retrieve. "potency_ranked" (default) returns the measurements that have a derivable pchembl_value, most potent first. "null_potency" returns exactly the measurements that have none — the rows the ranked view excludes, otherwise unreachable. The two partition the match set and stage to separate canvas tables. | potency_ranked |
| standard_type | No | Restrict to one measurement type, e.g. "IC50", "Ki", "EC50". Set this to compare potencies validly. | |
| target_chembl_id | No | ChEMBL target ID (from chembl_search_targets), e.g. "CHEMBL203". Supply this, molecule_chembl_id, or both — both narrows to that compound–target pair. | |
| pchembl_value_min | No | Minimum pchembl_value (−log10 molar potency), e.g. 7 keeps sub-100 nM activities. Only valid on the potency_ranked view — the null_potency rows have no pchembl_value to compare against. | |
| molecule_chembl_id | No | ChEMBL molecule ID (from chembl_search_molecules), e.g. "CHEMBL941". Supply this, target_chembl_id, or both — both narrows to that compound–target pair. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Guidance when no measurements matched, or how to SQL the spilled set. | |
| spilled | No | True when the view exceeded the preview and was staged on the canvas. | |
| canvas_id | No | Canvas ID holding the staged table — pass to chembl_dataframe_describe to list its columns, then to chembl_dataframe_query to run SQL over them. Null when canvas is disabled or nothing spilled. | |
| truncated | No | True when the CHEMBL_MAX_SPILL_ROWS cap was hit before the upstream view was exhausted — the staged table is a bounded slice, NOT the complete view, so aggregates over it are a sample. Narrow the filters to bring the view under the cap. | |
| activities | No | Bioactivity rows for the selected potency_view — the inline preview, or the full view when it fit without spilling. | |
| table_name | No | Canvas table name holding the staged rowset, and the FROM target for chembl_dataframe_query SQL — "bioactivities" for potency_ranked, "bioactivities_null_potency" for null_potency. Null when not spilled. | |
| totalCount | No | Total matching measurements upstream — the honest full count spanning BOTH potency views, before any preview cap. The staged/preview rows are the selected view of this. | |
| potency_view | No | Which view these rows came from: "potency_ranked" = measurements with a derivable pchembl_value; "null_potency" = measurements with none. Re-call with the other value to reach the rest of totalCount. | |
| appliedFilters | No | Filters as the server parsed them. | |
| canvasDisabled | No | True when CANVAS_PROVIDER_TYPE is not duckdb, so large sets could not spill — the inline rows are a capped preview, not the full set. | |
| staged_row_count | No | Rows actually registered on the canvas table. Null when nothing spilled. Below the view total when truncated is true. |