Onyx Model Builder guide for database-backed neural networks

Model Builder is a dashboard workspace for teams that want machine learning close to operational data. A model is scoped to the selected organization and database. Its training data comes from a saved query, its fields are mapped into feature and target tensors, and its published versions can be called through Onyx prediction endpoints.

The feature is best for tabular prediction, scoring, classification, multi-label outputs, vector regression, text or embedding experiments, and attention-based architectures over database rows. The screen is designed so model definitions, training history, and published artifacts stay attached to the database that produced them.

Open /model-builder in the Onyx Cloud Admin console after signing in. The workspace requires an active organization and database from the top context bar. The model list, saved query selector, and training actions are scoped to that database.

• Read model definitions: requires database read access.
• Create, edit, delete, train, complete, cancel, fine tune, and publish: require maintainer-level database access.
• Published model prediction: uses the database data API with read-only access and accepts either bearer auth or database API key credentials.
• Saved queries: create them in the Query Editor before selecting them as training data or prediction scripts.

The Model Builder screen is organized as a persistent model workspace. The header shows the selected model name, model count, configured layer count, expanded layer count, active organization, active database, and save status. Changes auto-save after a short debounce, and pending changes are flushed before training starts or the page unloads.

Training Setup connects the model definition to data. Choose a saved query from the Query Editor. The query can return row objects directly, or return a query definition that the backend streams before applying mappings.

Inputs and Outputs map query-row fields into model tensors. Inputs become features. Outputs become targets during training and structured prediction fields after publish. Each mapping has a name, row path, source type, invalid/null policy, optional default value, optional vector dimensions, and a transform pipeline.

Transform pipelines prepare raw row values for training. Transforms are ordered, can be moved up or down, and can be removed. Text Encoding and Column Pipeline can contain child transforms, allowing post-encoding or nested column processing.

The Architecture editor defines the neural network graph. Add layers or blocks, configure each node, reorder nodes with the arrow controls, and remove nodes as needed. Container nodes such as Residual, Repeat Block, and Multi-Head Output open nested editors for child layers.

Dense layers work on flat tensors. Attention layers work on token rows. To move between those shapes, use Feature Tokenizer or Reshape Interval to create tokens, then Token Pooling or Intervals To Flat before returning to Dense layers or output heads.

Architecture Checks appear above the root architecture when the graph violates shape or ordering rules. They are meant to catch errors before a training run starts.

• Feature Tokenizer first: a feature tokenizer must be the first executable layer when present.
• Attention needs tokens: Multi-Head Attention should follow Feature Tokenizer, Reshape Interval, or another token-producing layer.
• Token counts must match: Multi-Head Attention, Token Pooling, and Intervals To Flat must match upstream token count and token width.
• Dense layers need flat input: add Token Pooling or Intervals To Flat before Dense if the upstream shape is tokens.
• Residual branches preserve shape: a residual child sequence must return the same shape it received.
• Multi-Head Output is final: only one Multi-Head Output is supported, it must be final, and each output mapping can belong to only one head.

Start Training saves any pending edits, opens the Training dialog, and starts an asynchronous run. A model can have only one active running session at a time. The dialog separates in-process runs from previous training results.

Published Models are promoted versions created from completed training runs. Each card shows the published model name, run ID, version, publish time, model ID, best epoch loss, final epoch loss, and training time. Copy the Model ID when wiring applications to the prediction API.

Use Test Model to validate a published version without leaving the admin console. Raw Inputs mode creates a nested input object from the feature mapping row paths. Saved Script mode runs a saved query script, fills template parameters such as {{propertyId}}, and uses the script output rows as model inputs.

Published models can be called through the Onyx data API. The raw prediction endpoint accepts one object or an array of objects. The script prediction endpoint executes a saved script first, then maps its returned rows through the published model's feature mappings.

POST /data/my-database/model-builder/published-model/published-model-123/predict
Content-Type: application/json

{
  "inputs": [
    {
      "row": {
        "account_age_days": 420,
        "is_enterprise": true,
        "country_code": "US"
      }
    }
  ]
}

POST /data/my-database/model-builder/published-model/published-model-123/predict/script
Content-Type: application/json

{
  "scriptId": "training-row-script",
  "scriptParameters": {
    "customerId": "customer-123"
  }
}

{
  "publishedModelId": "published-model-123",
  "modelId": "model-abc",
  "inputCount": 1,
  "inputs": [
    {
      "row": {
        "account_age_days": 420,
        "is_enterprise": true,
        "country_code": "US"
      }
    }
  ],
  "predictions": [
    {
      "churnRisk": 0.1875
    }
  ],
  "rawPredictions": [[0.1875]]
}

Most Model Builder issues come from query shape, mapping paths, transform assumptions, or mismatched tensor dimensions. Keep Architecture Checks visible while iterating and run the saved query directly before starting expensive training runs.