TriQL.Client.Compression 1.0.0

Prefix Reserved
There is a newer version of this package available.
See the version list below for details.
dotnet add package TriQL.Client.Compression --version 1.0.0
                    
NuGet\Install-Package TriQL.Client.Compression -Version 1.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="TriQL.Client.Compression" Version="1.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="TriQL.Client.Compression" Version="1.0.0" />
                    
Directory.Packages.props
<PackageReference Include="TriQL.Client.Compression" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add TriQL.Client.Compression --version 1.0.0
                    
#r "nuget: TriQL.Client.Compression, 1.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package TriQL.Client.Compression@1.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=TriQL.Client.Compression&version=1.0.0
                    
Install as a Cake Addin
#tool nuget:?package=TriQL.Client.Compression&version=1.0.0
                    
Install as a Cake Tool

TriQL — .NET Client for Trino

TriQL is a from-scratch .NET client library for Trino. It provides two complementary programming surfaces over the same core engine:

  • TriQL SDK (TriQL.Client) — a low-level, async-first client that maps directly onto the Trino client protocol (sessions, statements, pages, rows). Intended for high-throughput data movement, custom tooling, and callers who want explicit control over paging and buffering.
  • TriQL ADO.NET Provider (TriQL.Data.ADO) — a complete System.Data.Common provider (DbConnection, DbCommand, DbDataReader, DbParameter, DbProviderFactory) so that Trino can be used from existing ADO.NET-based applications, ORMs, reporting tools, and BI connectors.

Additional packages:

  • TriQL.Client.Auth — cloud/enterprise authentication providers (Microsoft Entra ID, OAuth 2.0 client credentials) kept isolated so their dependencies never leak into the core client.
  • TriQL.Client.Compression — support for compressed spooled protocol payloads.

See docs/requirements.md for the full requirements specification and docs/implementation-plan.md for the phased delivery plan.

Status

Stable — 1.0.0. TriQL follows Semantic Versioning: breaking public-API changes only in a major version, additive API in minors, fixes in patches. The public API surface of each shipping package is locked by PublicAPI.Shipped.txt baselines and enforced at build time.

The one deliberately conservative default in 1.0 is the spooling protocol, which ships implemented and tested but opt-in — see Spooling protocol. Release notes for every version are published on GitHub Releases.

Requirements

  • .NET 10.0. netstandard2.0 and .NET Framework are not supported.
  • Trino server 466 or later (27 Nov 2024, the release that introduced the spooling protocol). This is the minimum version the conformance suite verifies against; the CI matrix covers {466, latest}.

Install

dotnet add package TriQL.Client        # streaming SDK
dotnet add package TriQL.Data.ADO      # ADO.NET provider
dotnet add package TriQL.Client.Auth   # optional: Entra ID / OAuth2 authentication
dotnet add package TriQL.Client.Compression  # optional: json+lz4 / json+zstd spooling codecs

Quick start: TriQL SDK (streaming)

using TriQL.Client;

var options = new TrinoSessionOptions
{
    Server = new Uri("https://trino.example.com:443/"),
    Catalog = "tpch",
    Schema = "tiny",
};

await using var client = new TrinoClient(options);
await using var resultSet = await client.ExecuteAsync("SELECT nationkey, name FROM tpch.tiny.nation ORDER BY nationkey");

await foreach (var row in resultSet.ReadRowsAsync())
{
    Console.WriteLine($"{row.GetInt64(0)}: {row.GetString(1)}");
}

Quick start: ADO.NET provider

using System.Data.Common;
using TriQL.Data.ADO;

var connectionString = new TrinoConnectionStringBuilder
{
    Server = "https://trino.example.com:443/",
    Catalog = "tpch",
    Schema = "tiny",
}.ConnectionString;

await using DbConnection connection = new TrinoConnection(connectionString);
await connection.OpenAsync();

await using var command = connection.CreateCommand();
command.CommandText = "SELECT nationkey, name FROM tpch.tiny.nation ORDER BY nationkey";

await using var reader = await command.ExecuteReaderAsync();
while (await reader.ReadAsync())
{
    Console.WriteLine($"{reader.GetInt64(0)}: {reader.GetString(1)}");
}

More runnable examples — including Microsoft Entra ID authentication and IAsyncEnumerable consumption — live in samples/TriQL.Samples.Console.

Spooling protocol (opt-in)

Trino's spooling protocol (compressed, object-storage-backed result segments) is implemented but ships off by default and opt-in in 1.0: TrinoSessionOptions.QueryDataEncodings defaults to an empty list, which forces the direct protocol. Enable it explicitly once your cluster is configured for spooling:

// The json+lz4 and json+zstd codecs live in the separate TriQL.Client.Compression package
// (kept out of TriQL.Client to stay dependency-free) and must be registered before executing
// a query that can select them, or the client throws TrinoProtocolException once the server
// picks an encoding it can't decode.
TriQL.Client.Compression.CompressionCodecs.RegisterAll();

options.QueryDataEncodings = ["json+zstd", "json+lz4", "json"];

Add a <PackageReference Include="TriQL.Client.Compression" /> to your project, or set QueryDataEncodings = ["json"] to enable spooling with the built-in uncompressed codec only, which needs no extra package or registration call.

Cluster prerequisites:

  • The coordinator must be spooling-configured (protocol.spooling.enabled=true, an object-storage spooling manager, and a shared secret key). A cluster without spooling simply returns direct-protocol data, which TriQL handles transparently.
  • The coordinator must be served over HTTPS, as well as the object store. TriQL requires https on every segment and acknowledgement URI, so a plain-HTTP coordinator with spooling enabled fails with TrinoProtocolException.

Related options on TrinoSessionOptions: SegmentFetchParallelism (default 4), MaxDecompressedSegmentBytes (default 256 MiB), and SegmentHostAllowlist (restricts which object-storage hosts segments may be fetched from; empty allows any https host).

The spooled path is verified in CI against a real spooling-configured Trino coordinator backed by MinIO (all three codecs, SSE-C encryption, segment acknowledgement, and cancellation cleanup). It stays opt-in for 1.0 because it has not yet been checked against AWS S3 or Azure Blob Storage, and throughput over the spooled path has not been benchmarked. Making it the default is planned for 1.1.0; that release will call out the behaviour change, and setting QueryDataEncodings = [] will keep the direct protocol.

Documentation

License

Apache-2.0

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
1.1.0 125 10/21/2026
1.0.0 114 10/5/2026
1.0.0-preview.1 87 9/12/2026