Skip to main content

GetItem Request Builder

Overview​

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

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

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

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

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

GetItem Configuration​

WithPrimaryKey (with only Partition key)​

Specifies the partition key of the item to get.

IGetItemEntityRequestBuilder<TEntity> WithPrimaryKey<TPk>(TPk pk);
info

It is required to specify the primary key for every GetItem request.

caution

Use this method if the table has only a partition key. If the table has both partition and sort keys, use WithPrimaryKey<TPk, TSk> instead.

Parameters​

  • pk: The partition key of the item.

Example​

builder = builder.WithPrimaryKey("partitionKey");

WithPrimaryKey (with both Partition and Sort keys)​

Specifies the partition and sort keys of the item to get.

IGetItemEntityRequestBuilder<TEntity> WithPrimaryKey<TPk, TSk>(TPk pk, TSk sk);
info

It is required to specify the primary key for every GetItem request.

caution

Use this method only if the table has both partition and sort keys. If the table only has a partition key, use WithPrimaryKey<TPk> instead.

Parameters​

  • pk: The partition key of the item.
  • sk: The sort key of the item.

Example​

builder = builder.WithPrimaryKey("partitionKey", "sortKey");

WithConsistentRead​

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

IGetItemEntityRequestBuilder<TEntity> WithConsistentRead(bool useConsistentRead);

If not specified, DynamoDB will use eventually consistent read.

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);

ReturnConsumedCapacity​

Specifies the consumed capacity details to include in the response.

IGetItemEntityRequestBuilder<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);

AsProjection (With Type)​

Projects the retrieved item 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.

IGetItemEntityRequestBuilder<TEntity, TProjection> AsProjection<TProjection>() where TProjection : class;

Example​

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

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

AsProjection (With Attributes)​

Projects the retrieved item 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.

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

Parameters​

  • properties: The attributes to project.

Example​

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

After execution, this GetItem 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.

IGetItemEntityRequestBuilder<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 GetItem 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.

AsDocument​

Represents the returned item as a Document.

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

IGetItemDocumentRequestBuilder<TEntity> AsDocument();

Example​

var documentBuilder = builder.AsDocument();

After execution, this GetItem request will return the Document instead of the original entity of the builder.

GetItem Execution​

There are 3 versions of every GetItem 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 AsDocument() was used, the execution method will contain the entity type of Document.

In all cases, the result will be null if the item does not exist.

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

ToItemAsync​

Executes the GetItem operation asynchronously and returns the item.

Task<TEntity?> ToItemAsync(CancellationToken cancellationToken = default);

Parameters​

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

Example​

var item = await builder.ToItemAsync();

ToResponseAsync​

Executes the GetItem operation asynchronously and returns the deserialized response. Besides the item, this response contains ConsumedCapacity property if ReturnConsumedCapacity was used.

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

Example​

var response = await builder.ToResponseAsync();
var item = response.Item;
var consumedCapacity = response.ConsumedCapacity;