# Services

> Read and write Blobs, Key-Values, Messages, Message Queues, Tables, and Time Series.

URL: https://www.trakhound.com/docs/trakhound-framework/services

Modules read and write data through common service interfaces instead of connecting to databases or brokers directly. A Service Package provides the implementation, and a [Router](https://www.trakhound.com/docs/trakhound-framework/routing) decides which Service handles each request. This lets the same module run against different storage and messaging systems without code changes.

Diagram: A module calls Client.Services.Tables.ReadMultiple. On a development Instance, the Router sends the call to a test database; on a production Instance, the same Package's call goes to the production SQL Server, whose connection details and credentials IT set in the Service configuration.

## Data Primitives

| Primitive | Use for | Client |
| --- | --- | --- |
| **Blobs** | Files and binary content stored by collection and key | `Client.Services.Blobs` |
| **Key-Values** | Simple values stored by collection and key | `Client.Services.KeyValues` |
| **Messages** | Publish / subscribe messaging by topic | `Client.Services.Messages` |
| **Message Queues** | Queued messages that are pulled and acknowledged | `Client.Services.MessageQueues` |
| **Tables** | Relational data, with requests that run on any supported database | `Client.Services.Tables` |
| **Time Series** | Values recorded over time, such as machine data | `Client.Services.TimeSeries` |

## Service Packages

| Package | Provides | License |
| --- | --- | --- |
| `TrakHound.FileSystem.Service` | Blobs stored on the file system | Free |
| `TrakHound.Memory.Service` | In-memory Key-Values (with a configurable `ttl`), Messages, and Message Queues, for development and tests without a broker | Free |
| `TrakHound.Http.Service` | Blobs, Key-Values, Messages, Message Queues, Tables, and Time Series from another TrakHound Instance over HTTP | Free |
| `TrakHound.Mqtt.Service` | Messages using an MQTT broker | Free |
| `TrakHound.RabbitMq.Service` | Message Queues using RabbitMQ | Free |
| `TrakHound.Redis.Service` | Key-Values using Redis | Free |
| `TrakHound.SqlServer.Service` | Tables using SQL Server | Free |
| `TrakHound.Postgres.Service` | Tables using PostgreSQL | Free |
| `TrakHound.Sqlite.Service` | Tables using SQLite, for small Instances and development, with no database server to run | Free |
| `TrakHound.Timescale.Service` | Time Series using TimescaleDB | Free |
| `TrakHound.InfluxDb.Service` | Time Series using InfluxDB 3 (1.x and 2.x aren't supported) | Free |

Install a Service Package, then create a Service configuration for it in the admin UI with the connection details (for example a server address) as parameters. Add the Service as a target of a Router to start using it.

## Credentials and Connection Details

Modules never need to know the address, username, or password of a database or message broker. Connection details and credentials are set once in a Service configuration on the Instance, usually by IT or an Instance administrator. Modules only call `Client.Services`, and the module's Router sends each request to the configured Service.

- **No secrets in code** - Credentials are not stored in module source code, Packages, or source control, so Packages can be shared and reviewed without exposing them
- **Separation of roles** - Engineers build modules, while IT controls which databases and brokers are used and the accounts used to connect to them
- **Change without redeploying** - Passwords can be rotated or a database can be moved by updating the Service configuration, without changing or republishing any module
- **Same Package in every environment** - A module tested against a development Service runs unchanged in production when its Router points to the production Service

For example, IT configures a SQL Server Service with the server and credentials, and a module reads from it without any connection details:

```
// No server, username, or password : the Router and Service configuration decide where data comes from
var parts = await Client.Services.Tables.ReadMultiple<Part>(TrakHoundTableRequest.Ansi("select * from \"parts\";"));
```

> Service configurations are stored in the Instance's configuration directory (see [Instances](https://www.trakhound.com/docs/trakhound-framework/instances)). Restrict access to that directory and to the admin UI the same way you would for any other server configuration that contains credentials.

## Using Services

Every module has a `Client`. Service calls return a `TrakHoundServiceResponse` with `Success`, `StatusCode`, `Message`, and (for reads) `Result`. Each call accepts an optional `routerId`; by default the module's configured Router is used. Check `Success` before using the result:

| Status Code | Meaning |
| --- | --- |
| 400 Bad Request | The call was wrong (ex. an error in a SQL query). |
| 403 Forbidden | The caller isn't allowed, or the module's [Zone](https://www.trakhound.com/docs/trakhound-framework/zones) denied the call ("Zone Access Denied"). |
| 404 Not Found | The Service doesn't have what was asked for. |
| 409 Conflict | The write conflicts with existing data (ex. a constraint violation). |
| 503 Not Available | The Service's backend can't be reached or isn't configured. Earlier versions returned 404 for this. |
| 504 Timeout | The backend didn't answer in time. |

[Routers](https://www.trakhound.com/docs/trakhound-framework/routing) use these results to decide whether to try a Route's next Target.

### Key-Values

```
await Client.Services.KeyValues.Publish("machines", "M001", "Running");

var response = await Client.Services.KeyValues.Read("machines", "M001");
if (response.Success) Console.WriteLine(response.Result);
```

Also: `ListCollections`, `ListKeys`, `Count`, `Delete`, and reading or publishing multiple keys at once.

### Blobs

```
using var file = File.OpenRead("report.pdf");
await Client.Services.Blobs.Upload("reports", "2026-10-01.pdf", file, "application/pdf");

var download = await Client.Services.Blobs.Download("reports", "2026-10-01.pdf");
```

Also: `ListCollections`, `ListKeys`, `List`, `Read` (information about a Blob), and `Delete`.

### Messages

```
await Client.Services.Messages.Publish("machines/M001/status", "Running", retain: true);

var stream = await Client.Services.Messages.SubscribeString("machines/+/status");
```

Publish strings, bytes, streams, or objects (serialized as JSON) with optional `retain` and `qos`. Subscribe to one or more topics, as raw messages, strings, or JSON (`SubscribeJson<T>`).

To publish many Messages, open a Publish Stream instead of calling `Publish` for each one:

```
var response = await Client.Services.Messages.PublishStreamString("line1/status", retain: false, qos: 0);
if (response.Success)
{
    using var stream = response.Result;
    stream.PublishFailed += (s, failure) => Log(TrakHoundLogLevel.Warning, $"{failure.Topic}: {failure.Message}");

    foreach (var status in statuses) stream.Push(status);
}
```

`PublishStreamBytes`, `PublishStreamJson<T>`, and `PublishStream()` (for Messages that carry their own Topic, Retain, and QoS) work the same way. Each Message is authorized and checked against the module's Zone like `Publish`. Over HTTP the stream is one WebSocket (`/_services/messages/publish/stream`), and only failures are sent back.

### Message Queues

```
// Returns the Message ID (the one set in the options, or the one the Service created)
var published = await Client.Services.MessageQueues.Publish("work-orders", workOrder);

var response = await Client.Services.MessageQueues.Pull("work-orders", count: 10);
foreach (var message in response.Content)
{
    var order = message.GetJsonContentObject<WorkOrder>();
    // ... handle the order, then remove it from the Queue
    await Client.Services.MessageQueues.Acknowledge("work-orders", [message.DeliveryId]);
}
```

- Each Message goes to one consumer. A pulled or subscribed Message stays on the Queue until it's `Acknowledge`d (removed) or `Reject`ed (returned to the Queue, or discarded with `requeue: false` so a Message that always fails doesn't loop).
- `autoAcknowledge: true` removes Messages as they're delivered, which loses a Message if the module stops before handling it.
- `Acknowledge` and `Reject` return a result for each Delivery ID. A Delivery ID stops working once the connection it was delivered on closes, and the Message is delivered again with `Redelivered` set.
- A Message has its `Content` (bytes) and the `MessageId`, `ContentType`, and `Headers` set with `TrakHoundQueuePublishOptions`. String content defaults to `text/plain` and objects to `application/json`.
- `Subscribe("work-orders", prefetch: 10)` limits how many unacknowledged Messages a subscription is sent at once. Pulling an empty Queue returns an empty list.
- To develop without a broker, use `TrakHound.Memory.Service`, whose Message Queues behave the same as RabbitMQ's.

### Tables

A module sends a Table Request, and the Table Service that receives it generates or selects the SQL for its own database (SQL Server, PostgreSQL, or SQLite). This also works through a Router or an HTTP Service, where the module can't know which database answers. Namespace: `TrakHound.Services.Tables`.

```
[Table("reading", "plant")]
[TableIndex("ix_reading_time", "timestamp desc")]
public class Reading
{
    [PrimaryKey] public string Id { get; set; }
    [Column(Length = 1000, Unicode = true)] public string Note { get; set; }
    public DateTime Timestamp { get; set; }
}

// Steps run in order, in one Transaction by default
var builder = new TrakHoundTableRequestBuilder();
builder.AppendEnsureTable<Reading>();
builder.AppendQuery("delete from \"plant\".\"reading\" where \"timestamp\" < @cutoff;");
builder.Parameters.Add("cutoff", cutoff);
builder.AppendMerge(readings);
var response = await Client.Services.Tables.Execute(builder.Build());

// A read needs only the "read" Permission
var request = TrakHoundTableRequest.Ansi("select * from \"plant\".\"reading\" order by \"timestamp\" desc;", skip: 0, take: 100);
var items = await Client.Services.Tables.ReadMultiple<Reading>(request);
```

Choose in this order:

1. **Typed steps** for creating Tables and writing rows, which differ the most between databases.
2. **The `ansi` subset** for other queries.
3. **Query Variants** only for SQL that can't be portable, or that you've tuned for one database.

| Builder method | What it does |
| --- | --- |
| `AppendEnsureTable<T>()` | Creates the Table and its Indexes if they don't exist. It doesn't change an existing Table's Columns. |
| `AppendInsert(items, overwrite)` | Writes rows. `overwrite` deletes rows with the same Primary Key first. |
| `AppendMerge(items)` | Updates rows matched by Primary Key and inserts new ones. |
| `AppendQuery(query, skip, take)` | Runs an `ansi` Query or Query Variants. `skip` and `take` page it, and it should have an `order by`. |
| `AppendDeleteBatched<T>(where, batchSize)` | Deletes rows in batches until none match, so a long delete doesn't hold one large Transaction. Build the Request with `useTransaction: false`. |

**The `ansi` subset** runs unchanged on every Service that lists `ansi` in its Dialects: `select`, `insert`, `update`, `delete`, joins, subqueries, CTEs, `group by`, window functions, and common functions, with double-quoted lowercase identifiers and `@name` Parameters. `top` and paging clauses, `[brackets]`, `isnull`, and `merge` aren't in it. A Service trusts the label, so `select top 5` labeled `ansi` runs on SQL Server and only fails elsewhere. Run your queries on more than one database (SQLite needs no setup) to catch this.

**Query Variants** hold a version of a Query per Dialect. The Service runs the first of its own Dialects that has one, and if none can run it returns 405 so a Router tries its next Target:

```
var variants = new TrakHoundTableQueryVariants
{
    ["ansi"] = "select ... portable SQL ...",
    ["sqlserver"] = "select ... tuned T-SQL ..."
};
var items = await Client.Services.Tables.ReadMultiple<Reading>(TrakHoundTableRequest.Query(variants));
```

- **Scripts** (ex. to create a View) are one `.sql` file per Dialect in a folder, sent with `TrakHoundTableRequest.Script`. Nothing records that a script has run, so it must be safe to run again.
- **Native SQL** - `ExecuteQuery(sql)` and `ExecuteNonQuery(sql)` with a string run the SQL as given on whichever database receives it, for tools and for modules that only ever use one database. `GetDialects()` lists what a Service runs.
- **Results** - `ReadMultiple` returns an empty list when there are no rows, while `ReadSingle` returns 404. A failed query keeps the Service's status code: 400 for errors in the query, 409 for constraint violations, 503 when the server can't be reached, and 504 for a timeout.
- **Differences to expect** - Text comparisons are case-insensitive on a default SQL Server database and case-sensitive on PostgreSQL and SQLite. Index names must be unique within a Schema on PostgreSQL and SQLite.

> `TrakHoundTableQueryBuilder` and the `TrakHoundTables` methods that generate SQL (ex. `GenerateInsert`) are obsolete. They still work, but the SQL they generate only runs on SQL Server. To move a Package, replace them with `TrakHoundTableRequestBuilder`, and replace `[Column(name, definition)]` with `Length` and `Unicode`.

### Time Series

Use a Time Series Service for values recorded over time, such as machine data. The module doesn't need to know which database stores them. Use Tables for relational data. Namespace: `TrakHound.Services.TimeSeries`.

```
var point = new TrakHoundTimeSeriesPoint
{
    Measurement = "spindle",
    Tags = new() { ["machine"] = "M1" },
    Timestamp = DateTimeOffset.UtcNow,
    Fields = new() { ["speed"] = 8000.0, ["state"] = "RUN" },
    Quality = TrakHoundTimeSeriesQuality.Good
};
await Client.Services.TimeSeries.Write(new[] { point });

// How long the machine was running in each hour
var response = await Client.Services.TimeSeries.Aggregate(new TrakHoundTimeSeriesAggregateQuery
{
    Measurement = "spindle",
    Tags = new() { ["machine"] = new[] { "M1" } },
    Fields = new[] { "state" },
    Start = start,
    Stop = stop,
    Interval = TimeSpan.FromHours(1),
    Functions = new[] { TrakHoundTimeSeriesAggregate.DurationInState },
    State = "RUN"
});
```

- **Tags** identify a Series, such as a machine or a line. Use a small set of known values: a value with no limit, such as a part serial number, can badly slow the database, so make it a Field.
- **Fields** hold the values: a double, long, bool, or string. A Field keeps its first type within a Measurement, and writing another type returns 400.
- **Quality** says whether a value can be trusted. `Quality` applies to every Field of a Point (it defaults to `Good`), and `Qualities` sets the Fields that differ. A Field with a null value records that it had no value at that time, and its Quality must be `Bad`.

| Call | What it does |
| --- | --- |
| `Write(points)` | Writes Points, and is safe to retry. A failed batch may be partly written, so retry the whole batch. |
| `Read(query)` | Reads the Points from `Start` (inclusive) to `Stop` (exclusive), with a Result for each Series. `Take` defaults to 1,000 per Series, up to 10,000, and `HasMore` says if Points were left out. |
| `ReadLatest(measurement, tags, fields)` | Reads the newest value of each Field of each Series. It can scan a lot of data on some databases, so use a Key-Value Service for values a dashboard reads often. |
| `Aggregate(query)` | Calculates `Functions` for each `Interval`, with a Result for each Series. |
| `ListMeasurements()`, `ListSeries(measurement, tags)`, `ListFields(measurement)` | List what has Points, and each Field's type. |
| `Delete(measurement, tags, start, stop)` | Deletes Points. Not every database can, so handle a 405 (ex. InfluxDB 3). |

`Tags` on a query and on `ReadLatest` can have several values for each Tag, to read many Series at once. The aggregate Functions are `Mean`, `Min`, `Max`, and `Sum` for numbers, and `Count`, `First`, `Last`, and `DurationInState` for any Field, plus `TimeWeightedMean`. `TimeWeightedMean` and `DurationInState` hold a value until the next Point, so use them for values that hold until they change. `Bad` values are skipped unless `IncludeBadQuality` is set, and `Fill` decides what an Interval without a value returns (`None`, `Null`, or `Previous`).

- **Retention** belongs to the database. The Services don't delete old Points, so add a TimescaleDB retention policy or use InfluxDB's retention period.
- **Admin UI** - **Explorer > Services > TimeSeries** browses Measurements, charts a Series' Points or a Function over a time range, and **Write** adds a test Point.
- **AI assistants** - The [MCP Server](https://www.trakhound.com/docs/trakhound-framework/mcp-server) has `timeseries_*` Tools to list, read, aggregate, and write. There's no Tool that deletes.
- **System API** - Other languages use `/_services/time-series` (see [Other Languages](https://www.trakhound.com/docs/trakhound-framework/clients)).

## Security

Each Service operation is a resource named `service:{serviceId}:{family}:{operation}` that requires `read`, or `write` for uploads, deletes, publishes, and non-queries. Calls made while handling an API request or App page run as the signed-in caller, so security profiles can control which users reach which data. Calls from Workers and Functions are trusted, and can be limited with [Zones](https://www.trakhound.com/docs/trakhound-framework/zones). See [Security](https://www.trakhound.com/docs/trakhound-framework/security).

## Create a Service

```
dotnet new trakhound.service
```

The template creates a Key-Value Service that holds its values in memory; replace them with calls to your backend. A Service inherits from `TrakHoundService` and implements one or more service interfaces:

| Interface | Callers use |
| --- | --- |
| `ITrakHoundBlobService` | `Client.Services.Blobs` |
| `ITrakHoundKeyValueService` | `Client.Services.KeyValues` |
| `ITrakHoundMessageService` | `Client.Services.Messages` |
| `ITrakHoundMessageQueueService` | `Client.Services.MessageQueues` |
| `ITrakHoundTableService` | `Client.Services.Tables` |
| `ITrakHoundTimeSeriesService` | `Client.Services.TimeSeries` |

- The constructor must be exactly `(ITrakHoundServiceConfiguration configuration)`. Services get their configuration, Volume, and Variables, but no `Client`.
- Override `CheckAvailability` to report whether the backend is reachable. Return results with `Ok`, `BadRequest` (400), `NotFound` (404), `Conflict` (409), `RouteNotConfigured` (405, the operation isn't supported), `InternalError` (500), `NotAvailable` (503), and `Timeout` (504). Pick the one that says what happened, because Routers use it to decide whether to try the next Target.
- The template's `Program.cs` creates the Service without an Instance and calls each operation. `TrakHound.Memory.Service` and `TrakHound.FileSystem.Service` are more complete examples.
- For a SQL database, derive a Table Service from `TrakHoundSqlTableService` and supply a `TrakHoundSqlDialect`. List `ansi` in its Dialects only if it passes the Framework's Tables conformance tests.
- A Time Series Service validates Requests with `TrakHoundTimeSeriesValidation` and builds Results with `TrakHoundTimeSeriesAggregates`, so its rules match the other Services. Return 405 from an operation the database can't do.
