Candidate sets

A candidate set is the space of possible decisions. Each candidate row represents one thing that Decisionhouse may select, assign, or allocate.

Create a candidate set

CREATE CANDIDATES items
DECISION KEY (id)
AS (
  SELECT *
  FROM inventory
);

The statement has three parts.

Part	Meaning
`items`	The name used by a later `DECIDE` query
`DECISION KEY (id)`	The columns that uniquely identify one candidate row
`AS (...)`	The SQL query that produces the candidates

The candidate set is new. It is not the source table, even when its query is a simple SELECT *.

Decision key

DECISION KEY is required and must contain at least one column. Every key column must exist in the SELECT output.

Use a composite key when one decision is identified by more than one value. An assignment candidate, for example, is often identified by both a resource and a workload.

CREATE CANDIDATES pool_assignments
DECISION KEY (pool_id, workload_id)
AS (
  SELECT
    pool_id,
    workload_id,
    capacity,
    demand,
    mem_gb,
    min_mem,
    cost
  FROM gpu_pools
  CROSS JOIN workloads
  WHERE mem_gb >= min_mem
);

The cross join creates one row per possible pool and workload pairing. The filter removes pairings that cannot satisfy the workload’s memory requirement.

Use ordinary SQL

The body of CREATE CANDIDATES can use the registered tables and normal SQL operations such as:

joins and cross joins
filters
computed columns
VALUES
projections that keep only the fields needed by the model

The query must ultimately produce one row per decision.

Evaluation and lifetime

Decisionhouse evaluates and caches the candidate query once when its definition runs. Candidate sets last only for the lifetime of the current CLI or server process.

A candidates file can contain several statements separated by semicolons.

Continue with DECIDE queries Declare unknown values, constraints, and the objective over a candidate set.