Method ExecuteAdminAsync

ExecuteAdminAsync(Char[], AdminOptions, CancellationToken)

On-premise only. Executes an administrative operation on the system.
Declaration
public Task<AdminResult> ExecuteAdminAsync(char[] statement, AdminOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type Name Description
Char[] statement The statement.
AdminOptions options (Optional) Options for admin DDL operation. If not specified or null, appropriate defaults will be used. See AdminOptions.
CancellationToken cancellationToken (Optional) Cancellation token.
Returns
Type Description
Task<AdminResult> Task returning AdminResult.
Remarks

The operations allowed are defined by Data Definition Language (DDL) portion of the query language that do not affect a specific table.For table-specific DLL operations use ExecuteTableDDLAsync.

Examples of statements passed to this method include:

  • CREATE NAMESPACE my_namespace
  • CREATE USER some_user IDENTIFIED BY password
  • CREATE ROLE some_role
  • GRANT ROLE some_role TO USER some_user

Some operations initiated by this API are performed by the service asynchronously and can be potentially long-running. For these operations, getting the result returned by this API does not imply operation completion. Call WaitForCompletionAsync(Nullable<TimeSpan>, Nullable<TimeSpan>, CancellationToken) on returned AdminResult to asynchronously wait for the operation completion. Alternatively, you may check the status of the running DDL operation by calling GetAdminStatusAsync(AdminResult, GetAdminStatusOptions, CancellationToken).

Other operations are immediate and are completed when the result from is returned. The readonly operations that don't modify system state but only return back information are immediate and will have State as Complete and non-null Output.

When an admin DDL operation is completed, the status of the operation should be Complete. To get only the final result, instead of this API, call ExecuteAdminWithCompletionAsync(Char[], AdminOptions, CancellationToken), which is equivalent to calling ExecuteAdminAsync(Char[], AdminOptions, CancellationToken) and then WaitForCompletionAsync(Nullable<TimeSpan>, Nullable<TimeSpan>, CancellationToken) (you can do this regardless of the type of the admin operation because WaitForCompletionAsync(Nullable<TimeSpan>, Nullable<TimeSpan>, CancellationToken) is a no-op if the operation has already completed).

This API takes the statement as char[] because some statements will include passwords and using an array allows the application to clear the memory to avoid keeping sensitive information in memory. For statements that don't include sensitive information, you may also use ExecuteAdminAsync(String, AdminOptions, CancellationToken).

Exceptions
Type Condition
ArgumentException If statement is null or invalid or options contains invalid values.
TimeoutException Operation has timed out.
InvalidOperationException The system is not in a valid state to perform this operation.
NoSQLException NoSQLException or one of its subclasses is thrown if operation cannot be performed for any other reason. See documentation for corresponding subclass of NoSQLException.
See Also

ExecuteAdminAsync(String, AdminOptions, CancellationToken)

On-premise only. Executes an administrative operation on the system.
Declaration
public Task<AdminResult> ExecuteAdminAsync(string statement, AdminOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type Name Description
String statement The statement.
AdminOptions options (Optional) Options for admin DDL operation. If not specified or null, appropriate defaults will be used. See AdminOptions.
CancellationToken cancellationToken (Optional) Cancellation token.
Returns
Type Description
Task<AdminResult> Task returning AdminResult.
Remarks
This API is the same as ExecuteAdminAsync(Char[], AdminOptions, CancellationToken) but takes the statement as a string and thus can be used if the statement does not contain sensitive information.
Exceptions
Type Condition
ArgumentException If statement is null or invalid or options contains invalid values.
TimeoutException Operation has timed out.
InvalidOperationException The system is not in a valid state to perform this operation.
NoSQLException NoSQLException or one of its subclasses is thrown if operation cannot be performed for any other reason. See documentation for corresponding subclass of NoSQLException.
See Also