---
title: "Start Query"
method: POST
path: "/start_query"
---

# Start Query

`POST /start_query`

Input structure / property constraints, and receive a query_id that will be used for getting results. The query is then initiated asynchronously.

Then, proceed to /check_query to find out when the query is done.

Body Parameters:

When using this API in isolation from the matcher application, "**use default value**" is recommended for some parameters.

- **snapquery_id**: **use default value**, matcher uses this to avoid duplicating query input state information for snapshotted queries
- **query_id**: **use default value**, matcher uses this to directly load results and avoid rerunning queries, for snapshotted queries
- **query_type**: "exact" or "substructure": specify what kind of search is run on the variable atoms (the atoms that change as part of the MMP transform)
- **transform_order**: **use default value**, currently only "first_order" transform queries are implemented, "second_order" could be implemented in the future
- **sketched_content**: These parameters refer to structures, and highlighted atoms, that would appear in sketcher(s) in the matcher frontend.
    - See documentation for **sketched_content** under the /validateSelection endpoint. **sketched_content** provides all structural constraints on returned transforms and MMPs. At least one of either mol1 or mol2 below must be filled out. For each mol, a molfile is required, and variable atom(s) indices are required. The environment atom indices are optional.
    - Not all atom/bond selections, as defined in **sketched_content**, will result in legal queries. The /validateSelection endpoint is designed to detect and correct atom/bond selections that will result in fruitless queries.
- **OPTIONAL_properties**: comma-separated string of property_name values. Require that both compounds in each MMP result have at least one of these OPTIONAL_properties
- **REQUIRED_properties**: comma-separated string of property_name values. Require that all compounds belonging to all MMPs in the results have every one of the REQUIRED_properties
    - At least one property must be provided, as either a REQUIRED or OPTIONAL property
- **advanced_options**: (OPTIONAL):
    - **variable_min_heavies**: integer, minimum number of heavy (non-H) atoms in BOTH variable fragments that comprise a transform, for every transform found by the query
    - **variable_max_heavies**: integer, maximum number of heavy (non-H) atoms in BOTH variable fragments that comprise a transform, for every transform found by the query
    - **compound_min_heavies**: integer, minimum number of heavy (non-H) atoms in BOTH compounds, in every MMP found by the query
    - **compound_max_heavies**: integer, maximum number of heavy (non-H) atoms in BOTH compounds, in every MMP found by the query
    - **aggregation_type**: **use default value**: matcher telegraphs this parameter to subsequent endpoints that control how results are displayed in the frontend (starting with /aggregate_transforms), but this parameter should not affect the initial query itself. Accepted values are "individual_transforms" or "group_by_fragment"
    - **snapfilter_id**: **use default value**, can be used to avoid duplication of output filters for snapshotted queries
    - **snapfilter_string**: **use default value**, used to filter output for snapshotted queries

Returns **query_id**, a positive integer

## Request body

- QueryInput
  - `snapquery_id` string
  - `query_id` integer
  - `query_type` 'exact' | 'substructure', required
  - `transform_order` 'first_order' | 'second_order', required
  - `sketched_content` SketchedContent, required
    - `mol1_molfile` string
    - `mol1_variable_atoms` string
    - `mol1_variable_bonds` string
    - `mol1_environment_atoms` string
    - `mol1_environment_bonds` string
    - `mol2_molfile` string
    - `mol2_variable_atoms` string
    - `mol2_variable_bonds` string
    - `mol2_environment_atoms` string
    - `mol2_environment_bonds` string
  - `REQUIRED_properties` string
  - `OPTIONAL_properties` string
  - `advanced_options` AdvancedOptions
    - `variable_min_heavies` integer
    - `variable_max_heavies` integer
    - `compound_min_heavies` integer
    - `compound_max_heavies` integer
    - `aggregation_type` 'individual_transforms' | 'group_by_fragment'
  - `snapfilter_id` string
  - `snapfilter_string` string

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/merck/apis/matcher-backend.md) · [All operations](https://skmtc.dev/merck/apis/matcher-backend/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/merck/matcher-backend/revisions/59028f512f31/schema)