Skip to main content

Query Request Builder

Overview​

This section describes the EfficientDynamoDb API for building the Query request.

The IQueryEntityRequestBuilder<TEntity> interface provides a builder pattern for constructing a Query operation in DynamoDB. It is designed to work with a database entity of type TEntity.

Use the DynamoDbContext.Query<TEntity>() method to get the builder:

var builder = ddbContext.Query<EntityClass>();

For the Query request you only required to specify key expression using the WithKeyExpression method. All other builder methods are optional and can be omitted. In this case, DynamoDB will use the default behavior.

Query Configuration​

WithKeyExpression (Explicit condition)​

Specifies the key expression for the Query operation.

IQueryEntityRequestBuilder<TEntity> WithKeyExpression(FilterBase keyExpressionBuilder);
info

It is required to specify the key expression for all DynamoDB queries.

Parameters​

Example​

var expr = Condition<EntityClass>.On(item => item.Pk).EqualTo("yourPartitionKey");
builder = builder.WithKeyExpression(expr);

WithKeyExpression (Function condition)​

Specifies the key expression for the Query operation.

IQueryEntityRequestBuilder<TEntity> WithKeyExpression(Func<EntityFilter<TEntity>, FilterBase> keySetup);
info

It is required to specify the key expression function for all DynamoDB queries.

Parameters​

Example​

builder = builder.WithKeyExpression(
    cond => cond.On(item => item.Pk).EqualTo("yourPartitionKey")
);

FromIndex​

Specifies the index name to use for the Query operation. Can be used for both GSI and LSI.

IQueryEntityRequestBuilder<TEntity> FromIndex(string indexName);

Parameters​

  • indexName: Name of the index.

Example​

builder = builder.FromIndex("indexName");

WithConsistentRead​

Specifies whether to use a consistent read in the Query operation.

IQueryEntityRequestBuilder<TEntity> WithConsistentRead(bool useConsistentRead);

If not specified, DynamoDB will use eventually consistent read.

caution

Consistent reads are not supported for queries against GSIs.

Parameters​

  • useConsistentRead: Set this to true if you want a consistent read. Otherwise, set it to false. Setting it to false is equivalent to not using the WithConsistentRead() method at all.

Example​

builder = builder.WithConsistentRead(true);

WithLimit​

Specifies the maximum number of items to query.

IQueryEntityRequestBuilder<TEntity> WithLimit(int limit);
info

The actual number of items returned may be less than specified when filter expression is present or if the scan operation exceeds the 1 MB limit or retrieved data. Refer to AWS developer guide for more information.

Parameters​

  • limit: Maximum number of items to query.

Example​

builder = builder.WithLimit(50);

ReturnConsumedCapacity​

Specifies the consumed capacity details to include in the response.

IQueryEntityRequestBuilder<TEntity> ReturnConsumedCapacity(ReturnConsumedCapacity consumedCapacityMode);

If not specified, no consumed capacity info is returned in the response.

Parameters​

  • consumedCapacityMode: The type of consumed capacity information to return. Setting it to ReturnConsumedCapacity.None is equivalent to not using the ReturnConsumedCapacity() method at all.

Example​

builder = builder.ReturnConsumedCapacity(ReturnConsumedCapacity.Total);

WithSelectMode​

Specify the select mode for the Query operation. It affects what data will be returned in response.

IQueryEntityRequestBuilder<TEntity> WithSelectMode(Select selectMode);

Parameters​

  • selectMode: Select mode to use for the query operation. Learn more about possible modes here.
tip

Use one of the projection methods instead of specifying SpecificAttributes mode:

Example​

builder = builder.WithSelectMode(Select.Count);

BackwardSearch​

Specifies if backward search should be used.

IQueryEntityRequestBuilder<TEntity> BackwardSearch(bool useBackwardSearch);

Parameters​

  • useBackwardSearch: true, if backward search should be used. Otherwise, false.

Example​

builder = builder.BackwardSearch(true);

WithFilterExpression (Explicit condition)​

Specifies the filter expression for the Query operation.

IQueryEntityRequestBuilder<TEntity> WithFilterExpression(FilterBase filterExpressionBuilder);

Parameters​

Example​

var expr = Condition<EntityClass>.On(item => item.FirstName).EqualTo("John");
builder = builder.WithFilterExpression(expr);

WithFilterExpression (Function condition)​

Specifies the filter expression function for the Query operation.

IQueryEntityRequestBuilder<TEntity> WithFilterExpression(Func<EntityFilter<TEntity>, FilterBase> filterSetup);

Parameters​

Example​

builder = builder.WithFilterExpression(
    cond => cond.On(item => item.FirstName).EqualTo("John")
);

WithPaginationToken​

Specifies the pagination token for the Query operation.

IQueryEntityRequestBuilder<TEntity> WithPaginationToken(string? paginationToken);

Parameters​

  • paginationToken: The pagination token to use. Passing null results in the same behavior as not specifying the pagination token at all.

Example​

builder = builder.WithPaginationToken("yourToken");

AsProjections (With type)​

Projects the retrieved items to the specified type. Only properties present in TProjection will be retrieved.

This method returns a different type of the builder to preserve the projection type. In case of chained calls and/or using var to save builder to a variable, the change of returned type may be unnoticeable. This is by design and you should be able to mix regular and projected builders.

IQueryEntityRequestBuilder<TEntity, TProjection> AsProjections<TProjection>() where TProjection : class;

Example​

Since the change of returned builder type, it can't be assigned to the same variable.

var projectedBuilder = builder.AsProjections<ProjectedEntity>();

AsProjections (With attributes)​

Projects the retrieved items to the specified type, but only retrieves the properties specified in properties parameter. Other properties will have default values.

Similarly to AsProjection<TProjection>(), this method returns a different type of the builder to preserve the projection type with all the previously explained consequences.

IQueryEntityRequestBuilder<TEntity, TProjection> AsProjections<TProjection>(params Expression<Func<TProjection, object>>[] properties) where TProjection : class;

Parameters​

  • properties: The attributes to project.

Example​

var projectedBuilder = builder.AsProjections<ProjectedEntity>(
    x => x.SomeProperty,
    x => x.AnotherProperty
);

After execution, this Query request will return instance of ProjectedEntity with only SomeProperty and AnotherProperty set. All other properties will have default values.

WithProjectedAttributes​

Specifies the attributes to project in the retrieved item. Only properties specified in properties will be retrieved. Other properties will have default values.

Contrary to AsProjection methods, WithProjectedAttributes doesn't change the type of returned entity and builder.

IQueryEntityRequestBuilder<TEntity> WithProjectedAttributes(params Expression<Func<TEntity, object>>[] properties);

Parameters​

  • properties: The attributes to project.

Example​

builder = builder.WithProjectedAttributes(
    x => x.SomeProperty,
    x => x.AnotherProperty
);

After execution, this Query request will return the original entity of the builder (in this example it's EntityClass) with only SomeProperty and AnotherProperty set. All other properties will have default values.

AsDocumets​

Represents the returned items as Document.

Similarly to AsProjection<TProjection>(), this operation returns different type of builder with all the previously explained consequences.

IQueryDocumentRequestBuilder<TEntity> AsDocuments();

Example​

var documentBuilder = builder.AsDocuments();

Query Execution​

There are 3 versions of every query execution method: regular, projected, and document. All versions have same parameters, the only difference is entity type returned value:

  • In most cases, the original entity TEntity is returned.
  • If AsProjection<TProjection>() was used during the configuration, the execution method will contain the entity type of TProjection.
  • If AsDocuments() was used, the execution method will contain the entity type of Document.

For simplicity, this document covers only regular version of execution methods.

ToListAsync​

Executes the Query operation and aggregates the results into a single list of items. This method will make at least one service call to DynamoDB and will continue making calls to fetch all available pages of results if necessary.

Task<IReadOnlyList<TEntity>> ToListAsync(CancellationToken cancellationToken = default);

Parameters​

  • cancellationToken: Token that can be used to cancel the task.

Example​

var items = await builder.ToListAsync();

ToPageAsync​

Executes the Query operation and returns the page of data with pagination token.

Task<PagedResult<TEntity>> ToPageAsync(CancellationToken cancellationToken = default);

Parameters​

  • cancellationToken: Token that can be used to cancel the task.

Example​

var page = await builder.ToPageAsync();
var items = page.Items;
var paginationToken = page.PaginationToken;

ToResponseAsync​

Executes the Query operation and returns the deserialized response.

Task<QueryEntityResponse<TEntity>> ToResponseAsync(CancellationToken cancellationToken = default);

Parameters​

  • cancellationToken: Token that can be used to cancel the task.

Example​

var response = await builder.ToResponseAsync();

ToAsyncEnumerable​

Executes the Query operation and returns the result as an async enumerable, with each item in the sequence representing a single retrieved item.

IAsyncEnumerable<TEntity> ToAsyncEnumerable();

Example​

await foreach(var item in builder.ToAsyncEnumerable())
{
    // Do something.
}

ToPagedAsyncEnumerable​

Executes the Query operation and returns the result as an async enumerable, with each item in the sequence representing a page of DynamoDB items.

IAsyncEnumerable<IReadOnlyList<TEntity>> ToPagedAsyncEnumerable();

Example​

await foreach(var page in builder.ToAsyncEnumerable())
{
    var items = page.Items;
    var paginationToken = page.PaginationToken;

    // Do something.
}