query_connectivity
Query synaptic connectivity between Drosophila neuron classes across ALL connectome datasets simultaneously for comparative connectomics. This is NOT pre-cached — it runs live queries, so expect slow responses (up to several minutes). Set both upstream_type AND downstream_type to filter connections between two specific neuron classes (e.g., "What Tm1→T3 connections exist across all datasets?"). At least one of upstream_type or downstream_type is required. CONSTRAINTS: Only accepts neuron class terms (OWL IDs like FBbt_00003789 or labels like "transmedullary neuron Tm1") — anatomical regions or neuropils (e.g., "lobula", "medulla") are NOT accepted. NOT suitable for individual neuron-to-neuron connections — for pre-computed connections of a single individual neuron, use run_query with NeuronNeuronConnectivityQuery instead. NOT for muscle/sense organ connections. RECOMMENDED DEFAULTS: weight=5, exclude_dbs=["hb","fafb"] unless user specifies otherwise. For both-ends queries, start with weight≥50 to avoid timeouts. RESULT SIZE: a broad query is enormous (a single class at weight=5 can be over 50,000 connections), so results are ranked strongest-first and paged — you get limit rows (default 50) plus a summary computed over ALL of them: totals, per-dataset counts, distinct neuron counts, and the top class pairs. Answer from the summary and quote a handful of rows; only page with offset if the user asks for specific further rows. WORKFLOW: Confirm parameters with user before querying. Use search_terms with filter_types ["neuron","class"] to validate/canonicalize neuron type labels. If zero results, try relaxation: lower weight to 1, then remove exclude_dbs filter, then try group_by_class=true — report what worked and let user decide. group_by_class=true is usually the better first call on a broad query: it rolls the connections up over the subclass hierarchy — a row per (upstream level, downstream level) with data, up to the queried term(s) — instead of returning every neuron pair. Because a connection counts toward every ancestor pair in scope, per-row pairwise_connections and total_weight do NOT sum to the raw connection counts, and a row appears for the queried class itself as well as each subclass with data.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many connection rows to return, strongest first (default 50). The summary always covers every connection found, not just the returned rows. Pass 0 for all rows — only do this on a query you already know is small, as broad queries return tens of thousands. | |
| offset | No | Row to start from within the strongest-first ranking (default 0). Re-running with the same limit and the next offset walks down the list. | |
| weight | No | Minimum synapse count threshold (recommended default: 5). Lower to 1 if initial query returns zero results as first relaxation step. | |
| exclude_dbs | No | Dataset symbols to exclude (recommended default: ["hb", "fafb"] to focus on newer datasets). Pass empty array [] to include all datasets. Must be the exact `symbol` field from list_connectome_datasets — currently BANC, fw, ol, mv, hb, mc, fafb, l1em. An unrecognised symbol is silently ignored by the server rather than reported, so a dataset name ("hemibrain", "male-cns", "flywire") excludes nothing and gives no warning. Call list_connectome_datasets rather than guessing. | |
| upstream_type | No | Upstream (presynaptic) neuron class — OWL ID (e.g., "FBbt_00003789") or full label (e.g., "transmedullary neuron Tm1"). Must be a neuron type/class, NOT an anatomical region. Use search_terms with filter_types ["neuron","class"] to validate/canonicalize labels before querying. | |
| group_by_class | No | If true, aggregate by class rolled up over the subclass hierarchy: a row appears for the queried class AND each subclass with data (a connection counts toward every ancestor pair up to the queried term(s), so per-row pairwise_connections / total_weight do not sum to the raw counts). Returns total_weight, average_weight, percent_connected and pairwise_connections per class pair, ranked by pairwise_connections. If false (default), returns individual neuron-to-neuron rows. | |
| downstream_type | No | Downstream (postsynaptic) neuron class — OWL ID or full label. Must be a neuron type/class, NOT an anatomical region. If user asks about connectivity to a brain region, first find neuron classes in that region using search_terms, then query for those classes. |