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 decides which Service handles each request. This lets the same module run against different storage and messaging systems without code changes.
Client.Services.Tables.ReadMultiple<Part>(request), with no server, username, or passwordsql-test with a test loginsql01 with credentials set by IT, encryptedData 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). 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 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 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
Acknowledged (removed) orRejected (returned to the Queue, or discarded withrequeue: falseso a Message that always fails doesn't loop). autoAcknowledge: trueremoves Messages as they're delivered, which loses a Message if the module stops before handling it.AcknowledgeandRejectreturn 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 withRedeliveredset.- A Message has its
Content(bytes) and theMessageId,ContentType, andHeadersset withTrakHoundQueuePublishOptions. String content defaults totext/plainand objects toapplication/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:
- Typed steps for creating Tables and writing rows, which differ the most between databases.
- The
ansisubset for other queries. - 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
.sqlfile per Dialect in a folder, sent withTrakHoundTableRequest.Script. Nothing records that a script has run, so it must be safe to run again. - Native SQL -
ExecuteQuery(sql)andExecuteNonQuery(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 -
ReadMultiplereturns an empty list when there are no rows, whileReadSinglereturns 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.
Qualityapplies to every Field of a Point (it defaults toGood), andQualitiessets the Fields that differ. A Field with a null value records that it had no value at that time, and its Quality must beBad.
| 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 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).
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. See 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 noClient. - Override
CheckAvailabilityto report whether the backend is reachable. Return results withOk,BadRequest(400),NotFound(404),Conflict(409),RouteNotConfigured(405, the operation isn't supported),InternalError(500),NotAvailable(503), andTimeout(504). Pick the one that says what happened, because Routers use it to decide whether to try the next Target. - The template's
Program.cscreates the Service without an Instance and calls each operation.TrakHound.Memory.ServiceandTrakHound.FileSystem.Serviceare more complete examples. - For a SQL database, derive a Table Service from
TrakHoundSqlTableServiceand supply aTrakHoundSqlDialect. Listansiin its Dialects only if it passes the Framework's Tables conformance tests. - A Time Series Service validates Requests with
TrakHoundTimeSeriesValidationand builds Results withTrakHoundTimeSeriesAggregates, so its rules match the other Services. Return 405 from an operation the database can't do.