From 1ad28827a9a26e24dca62fe02fdcb05f868e34ff Mon Sep 17 00:00:00 2001
From: Rajesh Digambar Bagul <102693488+Rajesh270712@users.noreply.github.com>
Date: Thu, 25 Jun 2026 21:08:26 +0530
Subject: [PATCH] Add XML docs for query execution extensions
---
SqlKata.Execution/Query.Extensions.cs | 554 ++++++++++++++++++++++++++
1 file changed, 554 insertions(+)
diff --git a/SqlKata.Execution/Query.Extensions.cs b/SqlKata.Execution/Query.Extensions.cs
index 4a19d608..502d12d8 100644
--- a/SqlKata.Execution/Query.Extensions.cs
+++ b/SqlKata.Execution/Query.Extensions.cs
@@ -6,88 +6,227 @@
namespace SqlKata.Execution
{
+ ///
+ /// Provides convenience extension methods for executing executable instances.
+ ///
public static class QueryExtensions
{
+ ///
+ /// Executes the query and returns whether it yields at least one row.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// when the query returns at least one row; otherwise, .
public static bool Exists(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Exists(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns whether it yields at least one row.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is when the query returns at least one row; otherwise, .
public async static Task ExistsAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExistsAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns whether it yields no rows.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// when the query returns no rows; otherwise, .
public static bool NotExist(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return !CreateQueryFactory(query).Exists(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns whether it yields no rows.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is when the query returns no rows; otherwise, .
public async static Task NotExistAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return !(await CreateQueryFactory(query).ExistsAsync(query, transaction, timeout, cancellationToken));
}
+ ///
+ /// Executes the query and maps all result rows to the requested type.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The sequence of materialized rows.
public static IEnumerable Get(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Get(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and maps all result rows to the requested type.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result contains the materialized rows.
public static async Task> GetAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).GetAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns all rows as dynamic objects.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The sequence of dynamic rows.
public static IEnumerable Get(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return query.Get(transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns all rows as dynamic objects.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result contains the dynamic rows.
public static async Task> GetAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await GetAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns the first row mapped to the requested type, or the default value when no row exists.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The first materialized row, or the default value for when no row exists.
public static T FirstOrDefault(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).FirstOrDefault(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns the first row mapped to the requested type, or the default value when no row exists.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the first materialized row, or the default value for when no row exists.
public static async Task FirstOrDefaultAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).FirstOrDefaultAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns the first row as a dynamic object, or when no row exists.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The first dynamic row, or when no row exists.
public static dynamic FirstOrDefault(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return FirstOrDefault(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns the first row as a dynamic object, or when no row exists.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the first dynamic row, or when no row exists.
public static async Task FirstOrDefaultAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await FirstOrDefaultAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns the first row mapped to the requested type.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The first materialized row.
public static T First(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).First(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns the first row mapped to the requested type.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the first materialized row.
public static async Task FirstAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).FirstAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns the first row as a dynamic object.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The first dynamic row.
public static dynamic First(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return First(query, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns the first row as a dynamic object.
+ ///
+ /// The executable query to run.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the first dynamic row.
public static async Task FirstAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await FirstAsync(query, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns a page of rows mapped to the requested type.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The one-based page number to retrieve.
+ /// The number of rows to include per page.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The requested pagination result.
public static PaginationResult Paginate(this Query query, int page, int perPage = 25, IDbTransaction transaction = null, int? timeout = null)
{
var db = CreateQueryFactory(query);
@@ -95,6 +234,17 @@ public static PaginationResult Paginate(this Query query, int page, int pe
return db.Paginate(query, page, perPage, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns a page of rows mapped to the requested type.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The one-based page number to retrieve.
+ /// The number of rows to include per page.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the requested pagination result.
public static async Task> PaginateAsync(this Query query, int page, int perPage = 25, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
var db = CreateQueryFactory(query);
@@ -102,36 +252,100 @@ public static async Task> PaginateAsync(this Query query,
return await db.PaginateAsync(query, page, perPage, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query and returns a page of dynamic rows.
+ ///
+ /// The executable query to run.
+ /// The one-based page number to retrieve.
+ /// The number of rows to include per page.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The requested pagination result.
public static PaginationResult Paginate(this Query query, int page, int perPage = 25, IDbTransaction transaction = null, int? timeout = null)
{
return query.Paginate(page, perPage, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query and returns a page of dynamic rows.
+ ///
+ /// The executable query to run.
+ /// The one-based page number to retrieve.
+ /// The number of rows to include per page.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the requested pagination result.
public static async Task> PaginateAsync(this Query query, int page, int perPage = 25, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await PaginateAsync(query, page, perPage, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query in chunks and stops when the callback returns .
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The callback that receives each chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
public static void Chunk(this Query query, int chunkSize, Func, int, bool> func, IDbTransaction transaction = null, int? timeout = null)
{
var db = CreateQueryFactory(query);
db.Chunk(query, chunkSize, func, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query in chunks and stops when the callback returns .
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The callback that receives each chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
public static async Task ChunkAsync(this Query query, int chunkSize, Func, int, bool> func, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
await CreateQueryFactory(query).ChunkAsync(query, chunkSize, func, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query in dynamic chunks and stops when the callback returns .
+ ///
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The callback that receives each dynamic chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
public static void Chunk(this Query query, int chunkSize, Func, int, bool> func, IDbTransaction transaction = null, int? timeout = null)
{
query.Chunk(chunkSize, func, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query in dynamic chunks and stops when the callback returns .
+ ///
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The callback that receives each dynamic chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
public static async Task ChunkAsync(this Query query, int chunkSize, Func, int, bool> func, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
await ChunkAsync(query, chunkSize, func, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query in chunks and invokes an action for each chunk.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The action that receives each chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
public static void Chunk(this Query query, int chunkSize, Action, int> action, IDbTransaction transaction = null, int? timeout = null)
{
var db = CreateQueryFactory(query);
@@ -139,61 +353,169 @@ public static void Chunk(this Query query, int chunkSize, Action
+ /// Asynchronously executes the query in chunks and invokes an action for each chunk.
+ ///
+ /// The row type to materialize.
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The action that receives each chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
public static async Task ChunkAsync(this Query query, int chunkSize, Action, int> action, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
await CreateQueryFactory(query).ChunkAsync(query, chunkSize, action, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes the query in dynamic chunks and invokes an action for each chunk.
+ ///
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The action that receives each dynamic chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
public static void Chunk(this Query query, int chunkSize, Action, int> action, IDbTransaction transaction = null, int? timeout = null)
{
query.Chunk(chunkSize, action, transaction, timeout);
}
+ ///
+ /// Asynchronously executes the query in dynamic chunks and invokes an action for each chunk.
+ ///
+ /// The executable query to run.
+ /// The maximum number of rows to read per chunk.
+ /// The action that receives each dynamic chunk and its one-based page number.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
public static async Task ChunkAsync(this Query query, int chunkSize, Action, int> action, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
await ChunkAsync(query, chunkSize, action, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an insert using key-value column data.
+ ///
+ /// The insert query to execute.
+ /// The column names and values to insert.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Insert(this Query query, IEnumerable> values, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsInsert(values), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an insert using key-value column data.
+ ///
+ /// The insert query to execute.
+ /// The column names and values to insert.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task InsertAsync(this Query query, IEnumerable> values, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsInsert(values), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a multi-row insert using explicit columns and value rows.
+ ///
+ /// The insert query to execute.
+ /// The columns to insert.
+ /// The row values to insert for the specified columns.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Insert(this Query query, IEnumerable columns, IEnumerable> valuesCollection, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsInsert(columns, valuesCollection), transaction, timeout);
}
+ ///
+ /// Asynchronously executes a multi-row insert using explicit columns and value rows.
+ ///
+ /// The insert query to execute.
+ /// The columns to insert.
+ /// The row values to insert for the specified columns.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task InsertAsync(this Query query, IEnumerable columns, IEnumerable> valuesCollection, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsInsert(columns, valuesCollection), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an insert that takes its values from another query.
+ ///
+ /// The insert query to execute.
+ /// The target columns to insert into.
+ /// The source query that provides inserted values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Insert(this Query query, IEnumerable columns, Query fromQuery, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsInsert(columns, fromQuery), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an insert that takes its values from another query.
+ ///
+ /// The insert query to execute.
+ /// The target columns to insert into.
+ /// The source query that provides inserted values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task InsertAsync(this Query query, IEnumerable columns, Query fromQuery, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsInsert(columns, fromQuery), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an insert using public properties from an object as column data.
+ ///
+ /// The insert query to execute.
+ /// The object whose public properties supply inserted column values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Insert(this Query query, object data, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsInsert(data), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an insert using public properties from an object as column data.
+ ///
+ /// The insert query to execute.
+ /// The object whose public properties supply inserted column values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task InsertAsync(this Query query, object data, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsInsert(data), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an insert and returns the generated identifier.
+ ///
+ /// The identifier type to return.
+ /// The insert query to execute.
+ /// The object whose public properties supply inserted column values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The generated identifier.
public static T InsertGetId(this Query query, object data, IDbTransaction transaction = null, int? timeout = null)
{
var db = CreateQueryFactory(query);
@@ -203,6 +525,16 @@ public static T InsertGetId(this Query query, object data, IDbTransaction tra
return row.Id;
}
+ ///
+ /// Asynchronously executes an insert and returns the generated identifier.
+ ///
+ /// The identifier type to return.
+ /// The insert query to execute.
+ /// The object whose public properties supply inserted column values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the generated identifier.
public static async Task InsertGetIdAsync(this Query query, object data, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
var row = await CreateQueryFactory(query)
@@ -211,6 +543,15 @@ public static async Task InsertGetIdAsync(this Query query, object data, I
return row.Id;
}
+ ///
+ /// Executes an insert with key-value column data and returns the generated identifier.
+ ///
+ /// The identifier type to return.
+ /// The insert query to execute.
+ /// The column names and values to insert.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The generated identifier.
public static T InsertGetId(this Query query, IEnumerable> data, IDbTransaction transaction = null, int? timeout = null)
{
var row = CreateQueryFactory(query).First>(query.AsInsert(data, true), transaction, timeout);
@@ -218,6 +559,16 @@ public static T InsertGetId(this Query query, IEnumerable
+ /// Asynchronously executes an insert with key-value column data and returns the generated identifier.
+ ///
+ /// The identifier type to return.
+ /// The insert query to execute.
+ /// The column names and values to insert.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the generated identifier.
public static async Task InsertGetIdAsync(this Query query, IEnumerable> data, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
var row = await CreateQueryFactory(query).FirstAsync>(query.AsInsert(data, true), transaction, timeout, cancellationToken);
@@ -225,56 +576,153 @@ public static async Task InsertGetIdAsync(this Query query, IEnumerable
+ /// Executes an update using key-value column data.
+ ///
+ /// The update query to execute.
+ /// The column names and values to update.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Update(this Query query, IEnumerable> values, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsUpdate(values), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an update using key-value column data.
+ ///
+ /// The update query to execute.
+ /// The column names and values to update.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task UpdateAsync(this Query query, IEnumerable> values, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsUpdate(values), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an update using public properties from an object as column data.
+ ///
+ /// The update query to execute.
+ /// The object whose public properties supply updated column values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Update(this Query query, object data, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsUpdate(data), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an update using public properties from an object as column data.
+ ///
+ /// The update query to execute.
+ /// The object whose public properties supply updated column values.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task UpdateAsync(this Query query, object data, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsUpdate(data), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an increment operation on a numeric column.
+ ///
+ /// The update query to execute.
+ /// The column to increment.
+ /// The amount to add to the column.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Increment(this Query query, string column, int value = 1, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsIncrement(column, value), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an increment operation on a numeric column.
+ ///
+ /// The update query to execute.
+ /// The column to increment.
+ /// The amount to add to the column.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task IncrementAsync(this Query query, string column, int value = 1, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsIncrement(column, value), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a decrement operation on a numeric column.
+ ///
+ /// The update query to execute.
+ /// The column to decrement.
+ /// The amount to subtract from the column.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Decrement(this Query query, string column, int value = 1, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsDecrement(column, value), transaction, timeout);
}
+ ///
+ /// Asynchronously executes a decrement operation on a numeric column.
+ ///
+ /// The update query to execute.
+ /// The column to decrement.
+ /// The amount to subtract from the column.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task DecrementAsync(this Query query, string column, int value = 1, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsDecrement(column, value), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a delete statement for the query.
+ ///
+ /// The delete query to execute.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The number of affected rows.
public static int Delete(this Query query, IDbTransaction transaction = null, int? timeout = null)
{
return CreateQueryFactory(query).Execute(query.AsDelete(), transaction, timeout);
}
+ ///
+ /// Asynchronously executes a delete statement for the query.
+ ///
+ /// The delete query to execute.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the number of affected rows.
public static async Task DeleteAsync(this Query query, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await CreateQueryFactory(query).ExecuteAsync(query.AsDelete(), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an aggregate query and returns its scalar value.
+ ///
+ /// The scalar result type.
+ /// The aggregate query to execute.
+ /// The aggregate operation name, such as count, avg, sum, min, or max.
+ /// The columns included in the aggregate operation.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The aggregate scalar value.
public static T Aggregate(this Query query, string aggregateOperation, string[] columns, IDbTransaction transaction = null, int? timeout = null)
{
var db = CreateQueryFactory(query);
@@ -282,12 +730,32 @@ public static T Aggregate(this Query query, string aggregateOperation, string
return db.ExecuteScalar(query.AsAggregate(aggregateOperation, columns), transaction, timeout);
}
+ ///
+ /// Asynchronously executes an aggregate query and returns its scalar value.
+ ///
+ /// The scalar result type.
+ /// The aggregate query to execute.
+ /// The aggregate operation name, such as count, avg, sum, min, or max.
+ /// The columns included in the aggregate operation.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the aggregate scalar value.
public static async Task AggregateAsync(this Query query, string aggregateOperation, string[] columns, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
var db = CreateQueryFactory(query);
return await db.ExecuteScalarAsync(query.AsAggregate(aggregateOperation, columns), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a count aggregate for the query.
+ ///
+ /// The scalar result type.
+ /// The query to count.
+ /// The optional columns to count.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The count result.
public static T Count(this Query query, string[] columns = null, IDbTransaction transaction = null, int? timeout = null)
{
var db = CreateQueryFactory(query);
@@ -295,6 +763,16 @@ public static T Count(this Query query, string[] columns = null, IDbTransacti
return db.ExecuteScalar(query.AsCount(columns), transaction, timeout);
}
+ ///
+ /// Asynchronously executes a count aggregate for the query.
+ ///
+ /// The scalar result type.
+ /// The query to count.
+ /// The optional columns to count.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the count value.
public static async Task CountAsync(this Query query, string[] columns = null, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
var db = CreateQueryFactory(query);
@@ -302,41 +780,117 @@ public static async Task CountAsync(this Query query, string[] columns = n
return await db.ExecuteScalarAsync(query.AsCount(columns), transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes an average aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to average.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The average value.
public static T Average(this Query query, string column, IDbTransaction transaction = null, int? timeout = null)
{
return query.Aggregate("avg", new[] { column }, transaction, timeout);
}
+ ///
+ /// Asynchronously executes an average aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to average.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the average value.
public static async Task AverageAsync(this Query query, string column, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await query.AggregateAsync("avg", new[] { column }, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a sum aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to sum.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The summed value.
public static T Sum(this Query query, string column, IDbTransaction transaction = null, int? timeout = null)
{
return query.Aggregate("sum", new[] { column }, transaction, timeout);
}
+ ///
+ /// Asynchronously executes a sum aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to sum.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the summed value.
public static async Task SumAsync(this Query query, string column, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await query.AggregateAsync("sum", new[] { column }, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a minimum aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to evaluate.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The minimum value.
public static T Min(this Query query, string column, IDbTransaction transaction = null, int? timeout = null)
{
return query.Aggregate("min", new[] { column }, transaction, timeout);
}
+ ///
+ /// Asynchronously executes a minimum aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to evaluate.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the minimum value.
public static async Task MinAsync(this Query query, string column, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await query.AggregateAsync("min", new[] { column }, transaction, timeout, cancellationToken);
}
+ ///
+ /// Executes a maximum aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to evaluate.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The maximum value.
public static T Max(this Query query, string column, IDbTransaction transaction = null, int? timeout = null)
{
return query.Aggregate("max", new[] { column }, transaction, timeout);
}
+ ///
+ /// Asynchronously executes a maximum aggregate for the specified column.
+ ///
+ /// The scalar result type.
+ /// The query to aggregate.
+ /// The column to evaluate.
+ /// The optional database transaction to use.
+ /// The optional command timeout, in seconds.
+ /// The token used to cancel the asynchronous operation.
+ /// A task whose result is the maximum value.
public static async Task MaxAsync(this Query query, string column, IDbTransaction transaction = null, int? timeout = null, CancellationToken cancellationToken = default)
{
return await query.AggregateAsync("max", new[] { column }, transaction, timeout, cancellationToken);