jaunty Api reference › Single Result Methods

Single Result Methods

Overview

Single result methods execute SQL commands and return a single entity or scalar value. These methods provide different behaviors for handling empty result sets and multiple results.

Methods

QueryFirst<T>(string sql)

Executes a query and returns the first entity from the result set. Throws an exception if the result set is empty.

Signature:

C# 
public static T QueryFirst<T>(this IDbConnection connection, string sql) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute

Returns:

  • T: The first entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty

Example:

C# 
var product = connection.QueryFirst<Product>("SELECT * FROM products WHERE id = 1");

QueryFirst<T>(string sql, object parameters)

Executes a parameterized query and returns the first entity from the result set. Throws an exception if the result set is empty.

Signature:

C# 
public static T QueryFirst<T>(this IDbConnection connection, string sql, object parameters) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • parameters: Parameters for the query

Returns:

  • T: The first entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty

QueryFirst<T>(string sql, CommandOptions<T> options)

Executes a query with command options and returns the first entity from the result set. Throws an exception if the result set is empty.

Signature:

C# 
public static T QueryFirst<T>(this IDbConnection connection, string sql, CommandOptions<T> options) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • options: Command options (transaction, timeout, custom mapper)

Returns:

  • T: The first entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty

QueryFirstOrDefault<T>(string sql)

Executes a query and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static T? QueryFirstOrDefault<T>(this IDbConnection connection, string sql) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute

Returns:

  • T?: The first entity of type T from the result set, or null if the result set is empty

Example:

C# 
var product = connection.QueryFirstOrDefault<Product>("SELECT * FROM products WHERE id = 999");
// Returns null if no product with id 999 exists

QueryFirstOrDefault<T>(string sql, object parameters)

Executes a parameterized query and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static T? QueryFirstOrDefault<T>(this IDbConnection connection, string sql, object parameters) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • parameters: Parameters for the query

Returns:

  • T?: The first entity of type T from the result set, or null if the result set is empty

QueryFirstOrDefault<T>(string sql, CommandOptions<T> options)

Executes a query with command options and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static T? QueryFirstOrDefault<T>(this IDbConnection connection, string sql, CommandOptions<T> options) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • options: Command options (transaction, timeout, custom mapper)

Returns:

  • T?: The first entity of type T from the result set, or null if the result set is empty

QuerySingle<T>(string sql)

Executes a query and returns the single entity from the result set. Throws an exception if the result set is empty or contains more than one element.

Signature:

C# 
public static T QuerySingle<T>(this IDbConnection connection, string sql) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute

Returns:

  • T: The single entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty or contains more than one element

Example:

C# 
var product = connection.QuerySingle<Product>("SELECT * FROM products WHERE id = 1");

QuerySingle<T>(string sql, object parameters)

Executes a parameterized query and returns the single entity from the result set. Throws an exception if the result set is empty or contains more than one element.

Signature:

C# 
public static T QuerySingle<T>(this IDbConnection connection, string sql, object parameters) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • parameters: Parameters for the query

Returns:

  • T: The single entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty or contains more than one element

QuerySingle<T>(string sql, CommandOptions<T> options)

Executes a query with command options and returns the single entity from the result set. Throws an exception if the result set is empty or contains more than one element.

Signature:

C# 
public static T QuerySingle<T>(this IDbConnection connection, string sql, CommandOptions<T> options) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • options: Command options (transaction, timeout, custom mapper)

Returns:

  • T: The single entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty or contains more than one element

QuerySingle<T>(string sql, object parameters, CommandOptions<T> options)

Executes a parameterised query with command options and returns the single entity from the result set. Throws an exception if the result set is empty or contains more than one element.

Signature:

C# 
public static T QuerySingle<T>(this IDbConnection connection, string sql, object parameters, CommandOptions<T> options) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • parameters: Parameters for the query
  • options: Command options (transaction, timeout, custom mapper)

Returns:

  • T: The single entity of type T from the result set

Exceptions:

  • InvalidOperationException: If the result set is empty or contains more than one element

QuerySingleOrDefault<T>(string sql)

Executes a query and returns the single entity from the result set or the default value if the result set is empty. Throws an exception if the result set contains more than one element.

Signature:

C# 
public static T? QuerySingleOrDefault<T>(this IDbConnection connection, string sql) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute

Returns:

  • T?: The single entity of type T from the result set, or null if the result set is empty

Exceptions:

  • InvalidOperationException: If the result set contains more than one element

Example:

C# 
var product = connection.QuerySingleOrDefault<Product>("SELECT * FROM products WHERE id = 1");
// Returns the product if found, null if not found, or throws if multiple products match

QuerySingleOrDefault<T>(string sql, object parameters)

Executes a parameterized query and returns the single entity from the result set or the default value if the result set is empty. Throws an exception if the result set contains more than one element.

Signature:

C# 
public static T? QuerySingleOrDefault<T>(this IDbConnection connection, string sql, object parameters) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • parameters: Parameters for the query

Returns:

  • T?: The single entity of type T from the result set, or null if the result set is empty

Exceptions:

  • InvalidOperationException: If the result set contains more than one element

QuerySingleOrDefault<T>(string sql, CommandOptions<T> options)

Executes a query with command options and returns the single entity from the result set or the default value if the result set is empty. Throws an exception if the result set contains more than one element.

Signature:

C# 
public static T? QuerySingleOrDefault<T>(this IDbConnection connection, string sql, CommandOptions<T> options) where T : new()

Parameters:

  • connection: The database connection
  • sql: The SQL query to execute
  • options: Command options (transaction, timeout, custom mapper)

Returns:

  • T?: The single entity of type T from the result set, or null if the result set is empty

Exceptions:

  • InvalidOperationException: If the result set contains more than one element

Async Variants

QueryFirstAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the first entity from the result set. Throws an exception if the result set is empty.

Signature:

C# 
public static ValueTask<T> QueryFirstAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

QueryFirstOrDefaultAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QueryFirstOrDefaultAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

QuerySingleAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the single entity from the result set. Throws an exception if the result set is empty or contains more than one element.

Signature:

C# 
public static ValueTask<T> QuerySingleAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

QuerySingleOrDefaultAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the single entity from the result set or the default value if the result set is empty. Throws an exception if the result set contains more than one element.

Signature:

C# 
public static ValueTask<T?> QuerySingleOrDefaultAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

Example:

C# 
var product = await connection.QueryFirstOrDefaultAsync<Product>("SELECT * FROM products WHERE id = 1");

Async Variants with Parameters

QueryFirstAsync<T>(string sql, object parameters, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query and returns the first entity from the result set.

Signature:

C# 
public static ValueTask<T> QueryFirstAsync<T>(this IDbConnection connection, string sql, object parameters, CancellationToken cancellationToken = default) where T : new()

QueryFirstOrDefaultAsync<T>(string sql, object parameters, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QueryFirstOrDefaultAsync<T>(this IDbConnection connection, string sql, object parameters, CancellationToken cancellationToken = default) where T : new()

QuerySingleAsync<T>(string sql, object parameters, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query and returns the single entity from the result set.

Signature:

C# 
public static ValueTask<T> QuerySingleAsync<T>(this IDbConnection connection, string sql, object parameters, CancellationToken cancellationToken = default) where T : new()

QuerySingleOrDefaultAsync<T>(string sql, object parameters, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query and returns the single entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QuerySingleOrDefaultAsync<T>(this IDbConnection connection, string sql, object parameters, CancellationToken cancellationToken = default) where T : new()

Example:

C# 
var product = await connection.QueryFirstOrDefaultAsync<Product>(
    "SELECT * FROM products WHERE category_id = @CategoryId",
    new { CategoryId = 1 },
    cancellationToken);

Async Variants with Command Options

QueryFirstAsync<T>(string sql, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a query with command options and returns the first entity from the result set.

Signature:

C# 
public static ValueTask<T> QueryFirstAsync<T>(this IDbConnection connection, string sql, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

QueryFirstOrDefaultAsync<T>(string sql, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a query with command options and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QueryFirstOrDefaultAsync<T>(this IDbConnection connection, string sql, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

QuerySingleAsync<T>(string sql, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a query with command options and returns the single entity from the result set.

Signature:

C# 
public static ValueTask<T> QuerySingleAsync<T>(this IDbConnection connection, string sql, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

QuerySingleOrDefaultAsync<T>(string sql, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a query with command options and returns the single entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QuerySingleOrDefaultAsync<T>(this IDbConnection connection, string sql, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

Example:

C# 
var product = await connection.QueryFirstAsync<Product>(
    "SELECT * FROM products",
    CommandOptions<Product>.WithTimeout(30),
    cancellationToken);

Async Variants with Parameters and Command Options

QueryFirstAsync<T>(string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query with command options and returns the first entity from the result set.

Signature:

C# 
public static ValueTask<T> QueryFirstAsync<T>(this IDbConnection connection, string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

QueryFirstOrDefaultAsync<T>(string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query with command options and returns the first entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QueryFirstOrDefaultAsync<T>(this IDbConnection connection, string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

QuerySingleAsync<T>(string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query with command options and returns the single entity from the result set.

Signature:

C# 
public static ValueTask<T> QuerySingleAsync<T>(this IDbConnection connection, string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

QuerySingleOrDefaultAsync<T>(string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default)

Asynchronously executes a parameterized query with command options and returns the single entity from the result set or the default value if the result set is empty.

Signature:

C# 
public static ValueTask<T?> QuerySingleOrDefaultAsync<T>(this IDbConnection connection, string sql, object parameters, CommandOptions<T> options, CancellationToken cancellationToken = default) where T : new()

Example:

C# 
var product = await connection.QueryFirstAsync<Product>(
    "SELECT * FROM products WHERE category_id = @CategoryId",
    new { CategoryId = 1 },
    CommandOptions<Product>.WithTimeout(30),
    cancellationToken);

Partial Mapping Variants

QueryPartialFirst<T>(string sql)

Executes a query and returns the first entity from the result set using partial mapping mode.

Signature:

C# 
public static T QueryPartialFirst<T>(this IDbConnection connection, string sql) where T : new()

QueryPartialFirstOrDefault<T>(string sql)

Executes a query and returns the first entity from the result set or the default value if the result set is empty using partial mapping mode.

Signature:

C# 
public static T? QueryPartialFirstOrDefault<T>(this IDbConnection connection, string sql) where T : new()

QueryPartialSingle<T>(string sql)

Executes a query and returns the single entity from the result set using partial mapping mode.

Signature:

C# 
public static T QueryPartialSingle<T>(this IDbConnection connection, string sql) where T : new()

QueryPartialSingleOrDefault<T>(string sql)

Executes a query and returns the single entity from the result set or the default value if the result set is empty using partial mapping mode.

Signature:

C# 
public static T? QueryPartialSingleOrDefault<T>(this IDbConnection connection, string sql) where T : new()

Example:

C# 
// Only selects a subset of columns - fine under partial mapping
var product = connection.QueryPartialFirst<Product>("SELECT product_id, product_name FROM products");

Async Partial Mapping Variants

QueryPartialFirstAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the first entity from the result set using partial mapping mode.

Signature:

C# 
public static ValueTask<T> QueryPartialFirstAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

QueryPartialFirstOrDefaultAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the first entity from the result set or the default value if the result set is empty using partial mapping mode.

Signature:

C# 
public static ValueTask<T?> QueryPartialFirstOrDefaultAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

QueryPartialSingleAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the single entity from the result set using partial mapping mode.

Signature:

C# 
public static ValueTask<T> QueryPartialSingleAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

QueryPartialSingleOrDefaultAsync<T>(string sql, CancellationToken cancellationToken = default)

Asynchronously executes a query and returns the single entity from the result set or the default value if the result set is empty using partial mapping mode.

Signature:

C# 
public static ValueTask<T?> QueryPartialSingleOrDefaultAsync<T>(this IDbConnection connection, string sql, CancellationToken cancellationToken = default) where T : new()

Example:

C# 
var product = await connection.QueryPartialFirstAsync<Product>(
    "SELECT product_id, product_name FROM products", cancellationToken);
← prev Schemas next → Special Types