Skip to content

Commit

Permalink
Add changefeed in readme and update limitations (#27073)
Browse files Browse the repository at this point in the history
### Packages impacted by this PR
@azure/cosmos

### Describe the problem that is addressed by this PR

- Add change feed pull model in readme.
- Update change feed limitations in readme.

### What are the possible designs available to address the problem? If
there are more than one possible design, why was the one in this PR
chosen?


### Are there test cases added in this PR? _(If not, why?)_


### Provide a list of related PRs _(if any)_


### Command used to generate this PR:**_(Applicable only to SDK release
request PRs)_

### Checklists
- [ ] Added impacted package name to the issue description
- [ ] Does this PR needs any fixes in the SDK Generator?** _(If so,
create an Issue in the
[Autorest/typescript](https://github.com/Azure/autorest.typescript)
repository and link it here)_
- [ ] Added a changelog (if necessary)
  • Loading branch information
amanrao23 authored Sep 11, 2023
1 parent 0237f04 commit a70d1ef
Showing 1 changed file with 70 additions and 3 deletions.
73 changes: 70 additions & 3 deletions sdk/cosmosdb/cosmos/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -254,6 +254,74 @@ for (const city of resources) {

For more information on querying Cosmos DB databases using the SQL API, see [Query Azure Cosmos DB data with SQL queries][cosmos_sql_queries].

### Change Feed Pull Model

Change feed can be fetched for a partition key, a feed range or an entire container.

To process the change feed, create an instance of `ChangeFeedPullModelIterator`. When you initially create `ChangeFeedPullModelIterator`, you must specify a required `changeFeedStartFrom` value inside the `ChangeFeedIteratorOptions` which consists of both the starting position for reading changes and the resource(a partition key or a FeedRange) for which changes are to be fetched. You can optionally use `maxItemCount` in `ChangeFeedIteratorOptions` to set the maximum number of items received per page.

Note: If no `changeFeedStartFrom` value is specified, then changefeed will be fetched for an entire container from Now().

There are four starting positions for change feed:

- `Beginning`

```js
// Signals the iterator to read changefeed from the beginning of time.
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning();
}
const iterator = container.getChangeFeedIterator(options);
```

- `Time`

```js
// Signals the iterator to read changefeed from a particular point of time.
const time = new Date("2023/09/11") // some sample date
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Time(time);
}
```

- `Now`

```js
// Signals the iterator to read changefeed from this moment onward.
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Now();
}
```

- `Continuation`

```js
// Signals the iterator to read changefeed from a saved point.
const continuationToken = "some continuation token recieved from previous request";
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Continuation(continuationToken);
}
```

Here's an example of fetching change feed for a partition key

```js
const partitionKey = "some-partition-Key-value";
const options = {
changeFeedStartFrom: ChangeFeedStartFrom.Beginning(partitionKey),
};

const iterator = container.items.getChangeFeedIterator(options);

while (iterator.hasMoreResults) {
const response = await iterator.readNext();
// process this response
}
```
Because the change feed is effectively an infinite list of items that encompasses all future writes and updates, the value of `hasMoreResults` is always `true`. When you try to read the change feed and there are no new changes available, you receive a response with `NotModified` status.

More detailed usage guidelines and examples of change feed can be found [here](https://learn.microsoft.com/azure/cosmos-db/nosql/change-feed-pull-model?tabs=javascript).

## Error Handling

The SDK generates various types of errors that can occur during an operation.
Expand Down Expand Up @@ -414,9 +482,8 @@ Currently the features below are **not supported**. For alternatives options, ch
* Aggregate cross-partition queries, like sorting, counting, and distinct, don't support continuation tokens. Streamable queries, like SELECT \* FROM <table> WHERE <condition>, support continuation tokens. See the "Workaround" section for executing non-streamable queries without a continuation token.
* Change Feed: Processor
* Change Feed: Read multiple partitions key values
* Change Feed: Read specific time
* Change Feed: Read from the beginning
* Change Feed: Pull model
* Change Feed pull model all versions and delete mode [#27058](https://github.com/Azure/azure-sdk-for-js/issues/27058)
* Change Feed pull model support for partial hierarchical partition keys [#27059](https://github.com/Azure/azure-sdk-for-js/issues/27059)
* Cross-partition ORDER BY for mixed types

### Control Plane Limitations:
Expand Down

0 comments on commit a70d1ef

Please sign in to comment.