Create materialize

Builds the declared version into immutable rows and answers 202 as soon as the attempt is on record.

POST /v1/dataset/{name}/materialize

Dataset → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/dataset/{name}/materialize`
Method	`POST`
Operation	`riskMaterializeDataset`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Builds the declared version into immutable rows and answers 202 as soon as the attempt is on record.

It never holds the request open for the work: a materialisation is a bounded warehouse scan, and letting an HTTP client's timeout be a data plane's timeout is how one tenant's retry loop becomes everyone's outage. ONE materialisation runs per org at a time; a second is refused rather than queued, because a queue admits the same work later and the honest answer to "again" while one is running is that one is running.

Only a DECLARED version is admitted. A published version is immutable, and a version whose earlier attempt did not complete is never re-attempted — that would union two runs' rows under one number and make the digest a lie. In both cases the answer is to declare a new version, which is what a second run over a moving source honestly is.

Request

1 field.

Field	In	Type	Required	Description
`name`	path	string	yes	Name is the dataset, from the path.

Response

Status	Body	Meaning
`202`	dataset.riskDataset	accepted
`default`	problem-details	refused

202 body — 30 fields.

Field	In	Type	Always	Description
`at`	body	string	—	At is when this version last changed state, RFC 3339 UTC.
`by`	body	string	—	By is who moved it there: the validated user, or the org itself when the caller is a machine with no user behind it.
`counts`	body	dataset.riskSplitCounts	—
`counts.judged`	body	integer (int64)	—	Judged is how many rows carry a disposition.
`counts.productive`	body	integer (int64)	—	Productive is how many judged rows carry the one disposition.
`counts.rows`	body	integer (int64)	—	Rows is how many rows the version holds across every split.
`counts.subjects`	body	integer (int64)	—	Subjects is how many distinct subjects the rows belong to.
`counts.test`	body	integer (int64)	—	Test is how many fall after the second cut — the LATEST slice, and the only one a score is honest about, since the split is temporal.
`counts.train`	body	integer (int64)	—	Train is how many rows fall before the first cut — the EARLIEST slice of the window, which is what a model is fitted on.
`counts.unproductive`	body	integer (int64)	—	Unproductive is how many carry the other.
`counts.val`	body	integer (int64)	—	Val is how many fall between the two cuts, held out for tuning.
`digest`	body	string	—	Digest fingerprints the SPEC and the ROWS together.
`name`	body	string	—	Name identifies the dataset across all of its versions.
`oversize`	body	integer (int64)	—	Oversize is how many of the window's subjects this version could NOT carry because their subject identity exceeds the plane's per-subject byte bound.
`refusal`	body	string	—	Refusal names why there are no bytes, when there are none.
`running`	body	boolean	—	Running is true while THIS process is materialising the version.
`share`	body	integer (int64)	—	Share is the fraction of the window's subjects admitted, in thousandths.
`spec`	body	dataset.riskDatasetSpec	—
`spec.cuts`	body	string[]	—	Cuts are the two RFC 3339 instants dividing train \| val \| test.
`spec.dims`	body	string[]	—	Dims are the coordinates to carry, by published name.
`spec.from`	body	string	—	From is where the event window opens, RFC 3339, INCLUSIVE.
`spec.horizon`	body	integer (int64)	—	Horizon is how many days a row must have aged before it may be admitted.
`spec.kind`	body	string	—	Kind narrows to one subject kind — person, session or account.
`spec.name`	body	string	—	Name identifies the dataset across its versions: lower-case letters, digits and hyphens, starting with a letter.
`spec.rows`	body	integer (int64)	—	Rows caps the materialisation.
`spec.seed`	body	string	—	Seed decides WHICH subjects are admitted when the window holds more rows than the cap allows.
`spec.to`	body	string	—	To is where the window ends, EXCLUSIVE, so two datasets meeting at one instant share no row.
`status`	body	string	—	Status is declared, materializing, ready or refused.
`truncated`	body	boolean	—	Truncated is true when the row cap bound before the window ran out.
`version`	body	integer (int64)	—	Version is which version this is, from 1 and monotone within the dataset.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo dataset materialize <name>

.ts

.py

.go

.rs

.java

import { Configuration, DatasetApi } from 'hanzoai';

const api = new DatasetApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.riskMaterializeDataset({ name: 'name' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import DatasetApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = DatasetApi(client).risk_materialize_dataset(name='name')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.DatasetAPI.RiskMaterializeDataset(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, dataset_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = dataset_api::risk_materialize_dataset(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.DatasetApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new DatasetApi(client).riskMaterializeDataset();

curl -X POST https://api.hanzo.ai/v1/dataset/<name>/materialize \
  -H "Authorization: Bearer $HANZO_API_KEY"

Tool dataset, op riskMaterializeDataset — POST the JSON-RPC envelope to https://api.hanzo.ai/v1/mcp.

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "dataset",
         "arguments": {
           "op": "riskMaterializeDataset",
           "input": {
             "name": "<name>"
           }
         }
       }
     }'

Dataset API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousExport dataset NextList resource tree — GET /v1/deploy/applications/{name}/resource-tree