Preview - FeedToken on Queries

[ealsur]

FeedToken on Queries

Description

This PR adds support for FeedToken on Queries while at the same time doing a redesign on the FeedToken public APIs.

The intent is to separate FeedToken types for operations to avoid the possibility of mixing tokens used on a Change Feed operation and tokens coming from a Query operation.

The APIs defined at #1210 and #1230 are valid but have slight modifications:

Token types

There are two distinct types: ChangeFeedToken and QueryFeedToken that are used on their specific operations.

Obtaining FeedTokens

There are no two distinct methods to request tokens, depending on the operation:

public Task<IReadOnlyList<ChangeFeedToken>> GetChangeFeedTokensAsync(CancellationToken cancellationToken = default(CancellationToken));

public Task<IReadOnlyList<QueryFeedToken>> GetQueryFeedTokensAsync(
            QueryDefinition queryDefinition,
            QueryRequestOptions queryRequestOptions = null,
            CancellationToken cancellationToken = default(CancellationToken));

The second method, for Queries, can return 1 token or multiple, depending on the nature of the query (for example, queries with DISTINCT do not make sense to be parallelized across multiple machines).

Using FeedTokens

The types are now used as input on their respective operation APIs:

public abstract FeedIterator GetItemQueryStreamIterator(
            QueryFeedToken feedToken,
            QueryRequestOptions requestOptions = null);

public abstract FeedIterator<T> GetItemQueryIterator<T>(
            QueryFeedToken feedToken,
            QueryRequestOptions requestOptions = null);

public abstract ChangeFeedIterator GetChangeFeedStreamIterator(
            ChangeFeedToken feedToken,
            ChangeFeedRequestOptions changeFeedRequestOptions = null);

public abstract ChangeFeedIterator<T> GetChangeFeedIterator(
            ChangeFeedToken feedToken,
            ChangeFeedRequestOptions changeFeedRequestOptions = null);

Serialization

Both token types are serializable and there are checks to avoid accidental mixing of format (for example, serialize a ChangeFeedToken and try to deserialize as QueryFeedToken, and viceversa).

Mixing containers

This PR also addresses another request and that is, to validate that a FeedToken generated for a container cannot be used in another container.

File reorganization

I reorganized FeedToken related files (that's why some files look completely modified) into their own folder, and tests have their own sub-namespace.

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

Closing issues

Closes #1262
Closes #1228
Closes #1226

[bchong95]

You don't know whether the ranges are sorted or not. When my epkrange PR goes through you can use the PartitionedSortedDistinct ranges class to uphold this invariant.

[bchong95]

Should it be PartitionKeyFeedToken instead? similar to MemoryStream vs Stream

[ealsur]

I was mainly using FeedToken as the prefix for all the related files/classes. Like FeedTokenEPKRange as in "a FeedToken for a EPK Range", or "a FeedToken for a PartitionKey".

[bchong95]

Does this enum need to be explicit?

[ealsur]

I always try to be explicit, but I don't have strong feelings

[bchong95]

Do we need to inherit from FeedToken?

[ealsur]

Not really. The class hierarchy is:

ChangeFeedToken and QueryFeedToken are the public abstract types
ChangeFeedTokenInternal and QueryFeedTokenInternal are the internal implementations

In order to reuse the actual FeedToken types (EPK, PKRangeId,...) I could had either duplicated the code or, as I did, use interfaces. So the EPK FeedToken can be wrapped/used through a ChangeFeedToken or through a QueryFeedToken leveraging the Internal interfaces.

[bchong95]

what's the difference between IQueryFeedToken and QueryFeedToken?

[ealsur]

QueryFeedToken is the public abstract contract.

IQueryFeedToken is the interface that lets me reuse a EPK FeedToken implementation in a QueryFeedToken.

EPK FeedToken implements 2 interfaces IChangeFeedToken and IQueryFeedToken.

QueryFeedTokenInternal accesses IQueryFeedToken, and ChangeFeedTokenInternal accesses IChangeFeedToken. That way, the same EPK FeedToken implementation can be reused without any code duplication.

[bchong95]

It's weird that you are taking rid and queryspec as input for this method.

[ealsur]

The reason for that is that I need to create a QueryFeedToken on the ExecutionContext after the results.

To create a QueryFeedToken I need the ContainerRid, and which is the query that executed. I couldn't find those pieces of information in the Execution Context or the Components.

[bchong95]

Does it make sense to return a FeedToken for ORDER BY queries? What if the user want's to scale the token? The results wouldn't be mergeable.

[ealsur]

That is why we always return 1. It cannot scale.

[bchong95]

Why is this changing?

[ealsur]

Because I am leveraging it on GetQueryFeedTokens to understand what type of QueryDefinition the user wants. I use the QueryExecutionPlan to see if it has any Aggregate/Distinct/etc and instead of returning multiple QueryFeedTokens for each PKRangeId, I return a single one signaling that that type of query cannot be scaled.

[bchong95]

Thanks for making this change. Excited to see customers start to use this API.

[ealsur]

Closing due to different approach being developed (feature still be delivered).