Updated to clarify what a checkpoint is and how to create it #790
+55
−34
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Deploying documentation with
|
| Latest commit: |
d85d9b5
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://3aa6bcef.documentation-21k.pages.dev |
| Branch Preview URL: | https://clarify-subscription-checkpo.documentation-21k.pages.dev |
Deflaimun
reviewed
Mar 4, 2025
| @@ -8,15 +8,15 @@ Subscriptions allow you to subscribe to a stream and receive notifications about | |||
|
|
|||
| You provide an event handler and an optional starting point to the subscription. The handler is called for each event from the starting point onward. | |||
|
|
|||
| If events already exist, the handler will be called for each event one by one until it reaches the end of the stream. From there, the server will notify the handler whenever a new event appears. | |||
| If events already exist, the handler will be called for each event one by one until it reaches the end of the stream. The server will then notify the handler whenever a new event appears. | |||
There was a problem hiding this comment.
Suggested change
| If events already exist, the handler will be called for each event one by one until it reaches the end of the stream. The server will then notify the handler whenever a new event appears. | |
| If events exist, the handler processes each event sequentially until it reaches the end of the stream. The server notifies the handler when a new event appears. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| @[code{subscribe-to-all}](@grpc:subscribing_to_stream.py;subscribing-to-streams.js;subscribing-to-streams.ts;subscribing_to_stream/SubscribingToStream.java;subscribing-to-streams/Program.cs;subscribingToStream.go;subscribing_to_stream.rs) | ||
|
|
||
| ## Subscribing from a specific position | ||
|
|
||
| The previous examples will subscribe to the stream from the beginning. This will end up calling the handler for every event in the stream and then wait for new events after that. | ||
| The previous examples subscribed to the stream from the beginning. This called the handler for every event in the stream and then waited for new events. |
There was a problem hiding this comment.
Suggested change
| The previous examples subscribed to the stream from the beginning. This called the handler for every event in the stream and then waited for new events. | |
| The previous examples subscribed to the stream from the beginning. That subscription invoked the handler for every event in the stream before waiting for new events. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| Both the stream and $all subscriptions accept a starting position if you want to read from a specific point onward. If events already exist at the position you subscribe to, they will be read on the server side and sent to the subscription. | ||
| Both stream and $all subscriptions accept a starting position if you want to read from a specific point onward. If events already exist at the position you subscribe to, they will be read on the server side and sent to the subscription. |
There was a problem hiding this comment.
Suggested change
| Both stream and $all subscriptions accept a starting position if you want to read from a specific point onward. If events already exist at the position you subscribe to, they will be read on the server side and sent to the subscription. | |
| Both stream and `$all` subscriptions let you specify a starting position for reading. If events exist at that position, the server reads and sends them to the subscription. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| The following subscribes to the stream `some-stream` at position `20`, this means that events `21` and onward will be handled: | ||
|
|
||
| @[code{subscribe-to-stream-from-position}](@grpc:subscribing_to_stream.py;subscribing-to-streams.js;subscribing-to-streams.ts;subscribing_to_stream/SubscribingToStream.java;subscribing-to-streams/Program.cs;subscribingToStream.go;subscribing_to_stream.rs) | ||
|
|
||
| ### Subscribing to $all | ||
|
|
||
| Subscribing to the `$all` stream is much like subscribing to a regular stream. The only difference is how you need to specify the stream position. For the `$all` stream, you have to provide a `Position` structure instead, which consists of two big integers - prepare and commit positions. The `Position` value can be `Start`, `End` or a `Position` created from a commit and prepare position. | ||
| Subscribing to the `$all` stream is similar to subscribing to a regular stream. The only difference is how to specify the stream position. For the `$all` stream, you must provide a `Position` structure instead, consisting of two big integers - prepare and commit positions. The `Position` value can be `Start`, `End`, or a `Position` created from a commit and prepare position. |
There was a problem hiding this comment.
Suggested change
| Subscribing to the `$all` stream is similar to subscribing to a regular stream. The only difference is how to specify the stream position. For the `$all` stream, you must provide a `Position` structure instead, consisting of two big integers - prepare and commit positions. The `Position` value can be `Start`, `End`, or a `Position` created from a commit and prepare position. | |
| Subscribing to the `$all` stream is similar to subscribing to a regular stream. The difference is how to specify the starting position. For the `$all` stream, provide a `Position` structure that consists of two big integers: the prepare and commit positions. Use `Start`, `End`, or create a `Position` from specific commit and prepare values. |
There was a problem hiding this comment.
not sure if that's 100% accurate. Please review
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| ::: tip | ||
| Server-side filtering introduced as a simpler alternative to projections. Before creating a projection to get the events you care about you should first consider filtering. | ||
| Server-side filtering was introduced as a simpler alternative to projections. You should consider filtering before creating a projection to include the events you care about. |
There was a problem hiding this comment.
Suggested change
| Server-side filtering was introduced as a simpler alternative to projections. You should consider filtering before creating a projection to include the events you care about. | |
| Server-side filtering offers a simpler alternative to projections. Filter events first to include the ones you care about. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| @[code{event-type-prefix}](@grpc:server_side_filtering.py;server-side-filtering.js;server-side-filtering.ts;server_side_filtering/ServerSideFiltering.java;server-side-filtering/Program.cs;serverSideFiltering.go;server_side_filtering.rs) | ||
|
|
||
| This will only subscribe to events with a type that begin with `customer-`. | ||
|
|
||
| #### Filtering by regular expression | ||
|
|
||
| If you want to subscribe to multiple event types then it might be better to provide a regular expression. | ||
| It might be advantageous to provide a regular expression when you want to subscribe to multiple event types. |
There was a problem hiding this comment.
Suggested change
| It might be advantageous to provide a regular expression when you want to subscribe to multiple event types. | |
| Provide a regular expression to subscribe to multiple event types. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| @[code{event-type-regex}](@grpc:server_side_filtering.py;server-side-filtering.js;server-side-filtering.ts;server_side_filtering/ServerSideFiltering.java;server-side-filtering/Program.cs;serverSideFiltering.go;server_side_filtering.rs) | ||
|
|
||
| This will subscribe to any event that begins with `user` or `company`. | ||
|
|
||
| ### Filtering by stream name | ||
|
|
||
| If you only want to subscribe to a stream with a given name there are two options. You can either use a regular expression or a prefix. | ||
| If you want to subscribe to a stream only with a given name, you have two options: you can use a regular expression or a prefix. |
There was a problem hiding this comment.
Suggested change
| If you want to subscribe to a stream only with a given name, you have two options: you can use a regular expression or a prefix. | |
| To subscribe to a stream by name, choose either a regular expression or a prefix. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| #### Filtering by regular expression | ||
|
|
||
| If you want to subscribe to multiple streams then it might be better to provide a regular expression. | ||
| If you want to subscribe to multiple streams, providing a regular expression might be better. |
There was a problem hiding this comment.
Suggested change
| If you want to subscribe to multiple streams, providing a regular expression might be better. | |
| To subscribe to multiple streams, use a regular expression. |
Deflaimun
reviewed
Mar 4, 2025
|
|
||
| @[code{stream-regex}](@grpc:server_side_filtering.py;server-side-filtering.js;server-side-filtering.ts;server_side_filtering/ServerSideFiltering.java;server-side-filtering/Program.cs;serverSideFiltering.go;server_side_filtering.rs) | ||
|
|
||
| This will subscribe to any stream with a name that begins with `account` or `savings`. | ||
|
|
||
| ## Checkpointing | ||
|
|
||
| There is one thing to consider with server-side filtering, and that is when events that match your filter are few and far between. In this scenario, you might find yourself in the situation where EventStoreDB has searched through 1 million events, and the last thing you want to happen is for the server to get to event 900k and then have your client crash. It won't have been able to take a checkpoint and upon a restart, you'd have to go back to the beginning and start again. | ||
| When a catch-up subscription is used to process an `$all` stream containing many events, the last thing you want is for your application to crash midway, forcing you to restart from the beginning. |
There was a problem hiding this comment.
Suggested change
| When a catch-up subscription is used to process an `$all` stream containing many events, the last thing you want is for your application to crash midway, forcing you to restart from the beginning. | |
| When processing an `$all` stream with a catch-up subscription, ensure your application stays stable to avoid restarting from the beginning. |
Deflaimun
reviewed
Mar 4, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.