Storing state

This section provides information on how to store or update state.

info

In the context of a task, command or step, please read the following sections:

API reference:

Required scopes:

Data/Buildby.Taskurai/state/create

When using transactions, these additional scopes are required:

Data/Buildby.Taskurai/state/delete

Optional scopes:

Data/Buildby.Taskurai/sensitive/read: Can return sensitive data.

Prerequisites

You have completed:

Setup sample application tutorial.
Deployed a default state store.

Storing or updating state

In this example, a shopping cart is created for a session. The state entry has a TTL of one hour, afterwards the state entry is automatically cleaned up.

// Get state client
var stateClient = taskurai.GetStateClient();

// Generate session id and demo cart
var sessionId = Guid.NewGuid();
var initialCart = new {
  Items = new Dictionary<string, int>()
  {
    {"Item A", 10},
    {"Item B", 5}
  }
};

// Store cart
var state = stateClient.SaveState(
  "DefaultStateStore", 
  new StateInput($"webshop::session::{sessionId}::cart")
  {
    Ttl = 60 * 60, // one hour
    Value = initialCart
  });

Console.WriteLine(JsonSerializer.Serialize(state, serializerOptions));

Next, run the console application to validate:

dotnet run

Sample output:

{
  "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::660ce0f8-b917-4bf6-a6d2-72a168c54abe::cart",
  "partitionKey": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::660ce0f8-b917-4bf6-a6d2-72a168c54abe::cart",
  "created": "2026-03-27T17:18:30.4071909+00:00",
  "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
  "modified": "2026-03-27T17:18:30.4071909+00:00",
  "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
  "tags": {},
  "stateStoreName": "DefaultStateStore",
  "isolationMode": true,
  "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
  "ttl": 3600,
  "etag": "\u0022ab002af1-0000-0d00-0000-69c6bbe60000\u0022",
  "value": {
    "items": {
      "Item A": 10,
      "Item B": 5
    }
  },
  "stateReference": {
    "stateStoreName": "DefaultStateStore",
    "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::660ce0f8-b917-4bf6-a6d2-72a168c54abe::cart"
  }
}

Saving blob state

In this example, an a large model (blob) is uploaded to the default state store.

// Get state client
var stateClient = taskurai.GetStateClient();

// Upload model
var state = stateClient.SaveBlobState(
  "DefaultStateStore", 
  new StateInput("ml::model::timeseries::forecasting::v1")
  {
    HasBlob = true,
    ContentType = "application/octet-stream",
    Tags = new Dictionary<string, string>
    {
      { "trained_on", "sales_forecasting_dataset" },
      { "accuracy", "0.95" },
      { "description", "Time series forecasting model for sales predictions" },
      { "model_type", "LSTM" },
      { "framework", "Deep Learning" }
    }
  }, 
  "model_timeseries_forecasting_v1.bin", // File location
  overwrite: true);

Console.WriteLine(JsonSerializer.Serialize(state, serializerOptions));

Next, run the console application to validate:

dotnet run

Sample output:

{
  "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::ml::model::timeseries::forecasting::v1",
  "partitionKey": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::ml::model::timeseries::forecasting::v1",
  "created": "2026-03-27T17:23:25.4413203+00:00",
  "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
  "modified": "2026-03-27T17:23:25.4413203+00:00",
  "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
  "hasBlob": true,
  "contentType": "application/octet-stream",
  "tags": {
    "trained_on": "sales_forecasting_dataset",
    "accuracy": "0.95",
    "description": "Time series forecasting model for sales predictions",
    "model_type": "LSTM",
    "framework": "Deep Learning"
  },
  "stateStoreName": "DefaultStateStore",
  "isolationMode": true,
  "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
  "ttl": -1,
  "etag": "\u0022ac00de08-0000-0d00-0000-69c6bd0d0000\u0022",
  "eTagBlob": "\u00220x8DE8C258DCE6990\u0022",
  "stateReference": {
    "stateStoreName": "DefaultStateStore",
    "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::ml::model::timeseries::forecasting::v1"
  }
}

Saving bulk state

In this example, multiple state items are stored in bulk.

// Get state client
var stateClient = taskurai.GetStateClient();

var sessionId = Guid.NewGuid();
var customerBag = new {
  Name = "Jane Doe",
  Email = "jane.doe@mail.net",
  Address = new {
    Street = "",
    Zipcode = "",
    City = "",
    State = "",
    Country = "US"
  }
};
var initialCart = new {
  Items = new Dictionary<string, int>()
  {
    {"Item A", 10},
    {"Item B", 5}
  }
};

var stateList = new List<StateInput>()
{
  new StateInput($"webshop::session::{sessionId}::customer")
  {
    Ttl = 60 * 60, // one hour
    Value = customerBag
  },
  new StateInput($"webshop::session::{sessionId}::cart")
  {
    Ttl = 60 * 60, // one hour
    Value = initialCart
  }
};

// Save state in one operation
var stateResponse = stateClient.SaveBulkState(
  "DefaultStateStore", 
  new StateBulkInput(stateList)
  {
    MaxParallelism = 10 // Server side: max 10 parallel operations
  });

Console.WriteLine(JsonSerializer.Serialize(stateResponse, serializerOptions));

Next, run the console application to validate:

dotnet run

Sample output:

[
  {
    "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::85909b63-91a1-4186-ba4a-5013d49e3a00::customer",
    "partitionKey": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::85909b63-91a1-4186-ba4a-5013d49e3a00::customer",
    "created": "2026-03-27T17:29:28.9058571+00:00",
    "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "modified": "2026-03-27T17:29:28.9058571+00:00",
    "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "tags": {},
    "stateStoreName": "DefaultStateStore",
    "isolationMode": true,
    "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
    "ttl": 3600,
    "etag": "\u0022ac00e922-0000-0d00-0000-69c6be780000\u0022",
    "value": {
      "name": "Jane Doe",
      "email": "jane.doe@mail.net",
      "address": {
        "street": "",
        "zipcode": "",
        "city": "",
        "state": "",
        "country": "US"
      }
    },
    "stateReference": {
      "stateStoreName": "DefaultStateStore",
      "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::85909b63-91a1-4186-ba4a-5013d49e3a00::customer"
    }
  },
  {
    "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::85909b63-91a1-4186-ba4a-5013d49e3a00::cart",
    "partitionKey": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::85909b63-91a1-4186-ba4a-5013d49e3a00::cart",
    "created": "2026-03-27T17:29:28.9058571+00:00",
    "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "modified": "2026-03-27T17:29:28.9058571+00:00",
    "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "tags": {},
    "stateStoreName": "DefaultStateStore",
    "isolationMode": true,
    "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
    "ttl": 3600,
    "etag": "\u0022ac00ea22-0000-0d00-0000-69c6be780000\u0022",
    "value": {
      "items": {
        "Item A": 10,
        "Item B": 5
      }
    },
    "stateReference": {
      "stateStoreName": "DefaultStateStore",
      "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::85909b63-91a1-4186-ba4a-5013d49e3a00::cart"
    }
  }
]

Saving bulk transactions

It is possible to use transactions to save/update or delete state entries.

warning

When using transactions, all state entries must have the same partition key.
Maximum number of operations in a transactional batch: 100

// Get state client
var stateClient = taskurai.GetStateClient();

var sessionId = Guid.NewGuid();
var customerBag = new {
  Name = "Jane Doe",
  Email = "jane.doe@mail.net",
  Address = new {
    Street = "",
    Zipcode = "",
    City = "",
    State = "",
    Country = "US"
  }
};
var initialCart = new {
  Items = new Dictionary<string, int>()
  {
    {"Item A", 10},
    {"Item B", 5}
  }
};
var coupon = new 
{
  Code = "ACTION20OFF",
  Value = 20.0
};

var partitionKey = $"webshop::session::{sessionId}";

// Add a coupon
var input = new StateInput($"webshop::session::{sessionId}::coupon")
{
  PartitionKey = partitionKey,
  Ttl = 160 * 60, // one hour
  Value = coupon
};
var couponState = stateClient.SaveState("DefaultStateStore", input);

// Start a transaction, add customer bag, cart and remove coupon
var stateTransactionInputList = new List<StateTransactionInput>()
{
  new StateTransactionInput()
  {
    Upsert = new StateUpsertOperation()
    {
      Input = new StateInput($"webshop::session::{sessionId}::customer")
      {
        Ttl = 60 * 60, // one hour
        Value = customerBag          
      }  
    }
  },
  new StateTransactionInput()
  {
    Upsert = new StateUpsertOperation()
    {
      Input = new StateInput($"webshop::session::{sessionId}::cart")
      {
        Ttl = 60 * 60, // one hour
        Value = initialCart
      }  
    }
  },
  new StateTransactionInput()
  {
    Delete = new StateDeleteOperation($"webshop::session::{sessionId}::coupon")
  }
};

var stateBulkTransactionInput = new StateBulkTransactionInput(stateTransactionInputList)
{
  PartitionKey = partitionKey,
  MaxParallelism = 10 // Maximum parallelism to handle blobs server side
};

var stateResponseList = stateClient.BulkTransaction("DefaultStateStore", stateBulkTransactionInput);

Console.WriteLine(JsonSerializer.Serialize(stateResponseList, serializerOptions));

Next, run the console application to validate:

dotnet run

Sample output:

[
  {
    "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::0f3e37ff-8d86-4319-b9d8-aa83501765bc::customer",
    "partitionKey": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::webshop::session::0f3e37ff-8d86-4319-b9d8-aa83501765bc",
    "created": "2026-03-27T17:30:43.5552601+00:00",
    "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "modified": "2026-03-27T17:30:43.5552601+00:00",
    "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "tags": {},
    "stateStoreName": "DefaultStateStore",
    "isolationMode": true,
    "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
    "ttl": 3600,
    "etag": "\u0022ac00c328-0000-0d00-0000-69c6bec30000\u0022",
    "value": {
      "name": "Jane Doe",
      "email": "jane.doe@mail.net",
      "address": {
        "street": "",
        "zipcode": "",
        "city": "",
        "state": "",
        "country": "US"
      }
    },
    "stateReference": {
      "stateStoreName": "DefaultStateStore",
      "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::0f3e37ff-8d86-4319-b9d8-aa83501765bc::customer"
    }
  },
  {
    "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::0f3e37ff-8d86-4319-b9d8-aa83501765bc::cart",
    "partitionKey": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::webshop::session::0f3e37ff-8d86-4319-b9d8-aa83501765bc",
    "created": "2026-03-27T17:30:43.5557889+00:00",
    "createdBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "modified": "2026-03-27T17:30:43.5557889+00:00",
    "modifiedBy": "d8e9cb3f-ffeb-4915-bb15-6681a3bcd175",
    "tags": {},
    "stateStoreName": "DefaultStateStore",
    "isolationMode": true,
    "isolationKey": "dd10b001-addd-45c2-94a6-932282b7515c",
    "ttl": 3600,
    "etag": "\u0022ac00c428-0000-0d00-0000-69c6bec30000\u0022",
    "value": {
      "items": {
        "Item A": 10,
        "Item B": 5
      }
    },
    "stateReference": {
      "stateStoreName": "DefaultStateStore",
      "id": "isolation::dd10b001-addd-45c2-94a6-932282b7515c::state::webshop::session::0f3e37ff-8d86-4319-b9d8-aa83501765bc::cart"
    }
  }
]

Prerequisites​

Storing or updating state​

Saving blob state​

Saving bulk state​

Saving bulk transactions​

Prerequisites

Storing or updating state

Saving blob state

Saving bulk state

Saving bulk transactions