Skip to main content

Overwriting at Refresh

Learn how to pass runtime parameters when you refresh a pipeline with coa refresh or the Start a Run endpoint, including how replacement works when you supply a parameters object.

COA CLI​

You can set parameters at refresh time by passing JSON after --parameters on coa refresh.

coa refresh --parameters '{ "foo": "bar" }'

When you use --parameters, follow the same rule as the Start a Run parameters field: pass the full runtime parameter map your Job needs for that Run, not a partial update layered on environment defaults. If you omit --parameters, the Run uses the environment defaults you configured in Build Settings > Environments for that environment.

REST API​

You can pass runtime parameters in the JSON body of a Start a Run request by including a parameters object with your credentials and runDetails.

When you include parameters, Coalesce treats it as the complete set of runtime parameters for that Run. Keys from environment-level parameters are not merged in automatically. If the environment defines parameters your Job still needs, you must include those keys and values in parameters, or omit parameters entirely so the Run uses environment defaults alone.

This behavior trades a larger request body for predictable results: you copy or reconstruct the full map in your client when you need overrides.

Use the following pattern when you only need to change a few values for one Run:

  1. Start from the full parameter map the environment would normally supply.
  2. Apply your overrides.
  3. Send the resulting object as parameters in the request.

If you send a partial map by mistake, omitted keys may be missing for that Run, which can cause Nodes or Jobs to miss values they expect.

Example​

Suppose your environment defines runtime parameters A and B. If your request body includes only C inside parameters:

{
  "parameters": {
    "C": "1"
  }
}

then A and B are not carried forward for that Run unless you also list them inside parameters. The effective runtime map for the Run is the object you sent under parameters.

When you want environment defaults only

If you don't need run-specific overrides, omit parameters from the request body so the Run picks up environment defaults without you copying the map client-side.

{
     "runDetails": {
          "environmentID": "4"
     },
     "userCredentials": {
          "platformKind": "databricks",
          "databricksClientSecret": "******",
          "databricksClientID": "*****",
          "databricksPath": "sql warehouse path",
          "databricksAuthType": "OAuthM2M"
     },
     "parameters": {
          "foo": "bar1"
     }
}

For how defaults and deploy-time overrides work, see Default Parameters and Overwriting at Deploy. The full request schema and credential shapes for refresh are documented on Start a Run.