Skip to content

glide_shared.commands.batch_options

BatchRetryStrategy

Defines a retry strategy for cluster batch requests, allowing control over retries in case of server or connection errors.

This strategy determines whether failed commands should be retried, impacting execution order and potential side effects.

Behavior
  • If retry_server_error is True, failed commands with a retriable error (e.g., TRYAGAIN) will be retried.
  • If retry_connection_error is True, batch requests will be retried on connection failures.
Cautions
  • Server Errors: Retrying may cause commands targeting the same slot to be executed out of order.
  • Connection Errors: Retrying may lead to duplicate executions, since the server might have already received and processed the request before the error occurred.
Example Scenario 
MGET key {key}:1
SET key "value"

Expected response when keys are empty: 

[None, None]
"OK"

However, if the slot is migrating, both commands may return an ASK error and be redirected. Upon ASK redirection, a multi-key command may return a TRYAGAIN error (triggering a retry), while the SET command succeeds immediately. This can result in an unintended reordering of commands if the first command is retried after the slot stabilizes: 

["value", None]
"OK"

Note

Currently, retry strategies are supported only for non-atomic batches.

Default

Both retry_server_error and retry_connection_error are set to False.

Parameters:

Name Type Description Default
retry_server_error bool

If True, failed commands with a retriable error (e.g., TRYAGAIN) will be automatically retried.

⚠️ Warning: Enabling this flag may cause commands targeting the same slot to execute out of order.

By default, this is set to False.

 False
retry_connection_error bool

If True, batch requests will be retried in case of connection errors.

⚠️ Warning: Retrying after a connection error may lead to duplicate executions, since the server might have already received and processed the request before the error occurred.

By default, this is set to False.

 False
Source code in doc-gen/valkey-glide/python/glide-shared/glide_shared/commands/batch_options.py 
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
class BatchRetryStrategy:
    """
    Defines a retry strategy for cluster batch requests, allowing control over retries in case of
    server or connection errors.

    This strategy determines whether failed commands should be retried, impacting execution order
    and potential side effects.

    Behavior:
        - If `retry_server_error` is `True`, failed commands with a retriable error (e.g.,
          `TRYAGAIN`) will be retried.
        - If `retry_connection_error` is `True`, batch requests will be retried on
          connection failures.

    Cautions:
        - **Server Errors:** Retrying may cause commands targeting the same slot to be executed
          out of order.
        - **Connection Errors:** Retrying may lead to duplicate executions, since the server might
          have already received and processed the request before the error occurred.

    Example Scenario:
        ```
        MGET key {key}:1
        SET key "value"
        ```

        Expected response when keys are empty:
        ```
        [None, None]
        "OK"
        ```

        However, if the slot is migrating, both commands may return an `ASK` error and be
        redirected. Upon `ASK` redirection, a multi-key command may return a `TRYAGAIN`
        error (triggering a retry), while the `SET` command succeeds immediately. This
        can result in an unintended reordering of commands if the first command is retried
        after the slot stabilizes:
        ```
        ["value", None]
        "OK"
        ```

    Note:
        Currently, retry strategies are supported only for non-atomic batches.

    Default:
        Both `retry_server_error` and `retry_connection_error` are set to `False`.

    Args:
        retry_server_error (bool): If `True`, failed commands with a retriable error (e.g., `TRYAGAIN`)
            will be automatically retried.

            ⚠️ **Warning:** Enabling this flag may cause commands targeting the same slot to execute
            out of order.

            By default, this is set to `False`.

        retry_connection_error (bool): If `True`, batch requests will be retried in case of connection errors.

            ⚠️ **Warning:** Retrying after a connection error may lead to duplicate executions, since
            the server might have already received and processed the request before the error occurred.

            By default, this is set to `False`.

    """

    def __init__(
        self,
        retry_server_error: bool = False,
        retry_connection_error: bool = False,
    ):
        """
        Initialize a BatchRetryStrategy.

        Args:
            retry_server_error (bool): If `True`, failed commands with a retriable error (e.g., `TRYAGAIN`)
                will be automatically retried.

                ⚠️ **Warning:** Enabling this flag may cause commands targeting the same slot to execute
                out of order.

                By default, this is set to `False`.

            retry_connection_error (bool): If `True`, batch requests will be retried in case of connection errors.

                ⚠️ **Warning:** Retrying after a connection error may lead to duplicate executions, since
                the server might have already received and processed the request before the error occurred.

                By default, this is set to `False`.

        """
        self.retry_server_error = retry_server_error
        self.retry_connection_error = retry_connection_error

BaseBatchOptions

Base options settings class for sending a batch request. Shared settings for standalone and cluster batch requests.

Parameters:

Name Type Description Default
timeout Optional[int]

The duration in milliseconds that the client should wait for the batch request to complete. This duration encompasses sending the request, awaiting a response from the server, and any required reconnections or retries. If the specified timeout is exceeded for a pending request, it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.

 None
Source code in doc-gen/valkey-glide/python/glide-shared/glide_shared/commands/batch_options.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
class BaseBatchOptions:
    """
    Base options settings class for sending a batch request. Shared settings for standalone and
    cluster batch requests.

    Args:
        timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
            to complete. This duration encompasses sending the request, awaiting a response from the server,
            and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
            it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
    """

    def __init__(
        self,
        timeout: Optional[int] = None,
    ):
        """
        Initialize BaseBatchOptions.

        Args:
            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
                to complete. This duration encompasses sending the request, awaiting a response from the server,
                and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
                it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
        """
        self.timeout = timeout

BatchOptions

Bases: BaseBatchOptions

Options for a batch request for a standalone client.

Parameters:

Name Type Description Default
timeout Optional[int]

The duration in milliseconds that the client should wait for the batch request to complete. This duration encompasses sending the request, awaiting a response from the server, and any required reconnections or retries. If the specified timeout is exceeded for a pending request, it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.

 None
Source code in doc-gen/valkey-glide/python/glide-shared/glide_shared/commands/batch_options.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
class BatchOptions(BaseBatchOptions):
    """
    Options for a batch request for a standalone client.

    Args:
        timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
            to complete. This duration encompasses sending the request, awaiting a response from the server,
            and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
            it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
    """

    def __init__(
        self,
        timeout: Optional[int] = None,
    ):
        """
        Options for a batch request for a standalone client

        Args:
            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
                to complete. This duration encompasses sending the request, awaiting a response from the server,
                and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
                it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.
        """
        super().__init__(timeout)

ClusterBatchOptions

Bases: BaseBatchOptions

Options for cluster batch operations.

Parameters:

Name Type Description Default
timeout Optional[int]

The duration in milliseconds that the client should wait for the batch request to complete. This duration encompasses sending the request, awaiting a response from the server, and any required reconnections or retries. If the specified timeout is exceeded for a pending request, it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.

 None
route Optional[TSingleNodeRoute]

Configures single-node routing for the batch request. The client will send the batch to the specified node defined by route.

If a redirection error occurs:

  • For Atomic Batches (Transactions), the entire transaction will be redirected.
  • For Non-Atomic Batches (Pipelines), only the commands that encountered redirection errors will be redirected.
 None
retry_strategy Optional[BatchRetryStrategy]

⚠️ Please see BatchRetryStrategy and read carefully before enabling these options.

Defines the retry strategy for handling cluster batch request failures.

This strategy determines whether failed commands should be retried, potentially impacting execution order.

  • If retry_server_error is True, retriable errors (e.g., TRYAGAIN) will trigger a retry.
  • If retry_connection_error is True, connection failures will trigger a retry.

Warnings:

  • Retrying server errors may cause commands targeting the same slot to execute out of order.
  • Retrying connection errors may lead to duplicate executions, as it is unclear which commands have already been processed.

Note: Currently, retry strategies are supported only for non-atomic batches.

Recommendation: It is recommended to increase the timeout in timeout when enabling these strategies.

Default: Both retry_server_error and retry_connection_error are set to False.

 None
Source code in doc-gen/valkey-glide/python/glide-shared/glide_shared/commands/batch_options.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
class ClusterBatchOptions(BaseBatchOptions):
    """
    Options for cluster batch operations.

    Args:
        timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
            to complete. This duration encompasses sending the request, awaiting a response from the server,
            and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
            it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.

        route (Optional[TSingleNodeRoute]): Configures single-node routing for the batch request. The client
            will send the batch to the specified node defined by `route`.

            If a redirection error occurs:

            - For Atomic Batches (Transactions), the entire transaction will be redirected.
            - For Non-Atomic Batches (Pipelines), only the commands that encountered redirection errors
              will be redirected.

        retry_strategy (Optional[BatchRetryStrategy]): ⚠️ **Please see `BatchRetryStrategy` and read carefully before enabling these
            options.**

            Defines the retry strategy for handling cluster batch request failures.

            This strategy determines whether failed commands should be retried, potentially impacting
            execution order.

            - If `retry_server_error` is `True`, retriable errors (e.g., TRYAGAIN) will
              trigger a retry.
            - If `retry_connection_error` is `True`, connection failures will trigger a
              retry.

            **Warnings:**

            - Retrying server errors may cause commands targeting the same slot to execute out of
              order.
            - Retrying connection errors may lead to duplicate executions, as it is unclear which
              commands have already been processed.

            **Note:** Currently, retry strategies are supported only for non-atomic batches.

            **Recommendation:** It is recommended to increase the timeout in `timeout`
            when enabling these strategies.

            **Default:** Both `retry_server_error` and `retry_connection_error` are set to
            `False`.

    """

    def __init__(
        self,
        timeout: Optional[int] = None,
        route: Optional[TSingleNodeRoute] = None,
        retry_strategy: Optional[BatchRetryStrategy] = None,
    ):
        """
        Initialize ClusterBatchOptions.

        Args:
            timeout (Optional[int]): The duration in milliseconds that the client should wait for the batch request
                to complete. This duration encompasses sending the request, awaiting a response from the server,
                and any required reconnections or retries. If the specified timeout is exceeded for a pending request,
                it will result in a timeout error. If not explicitly set, the client's default request timeout will be used.

            route (Optional[TSingleNodeRoute]): Configures single-node routing for the batch request. The client
                will send the batch to the specified node defined by `route`.

                If a redirection error occurs:

                - For Atomic Batches (Transactions), the entire transaction will be redirected.
                - For Non-Atomic Batches (Pipelines), only the commands that encountered redirection errors
                will be redirected.

            retry_strategy (Optional[BatchRetryStrategy]): ⚠️ **Please see `BatchRetryStrategy` and read carefully before enabling these
                options.**

                Defines the retry strategy for handling cluster batch request failures.

                This strategy determines whether failed commands should be retried, potentially impacting
                execution order.

                - If `retry_server_error` is `True`, retriable errors (e.g., TRYAGAIN) will
                trigger a retry.
                - If `retry_connection_error` is `True`, connection failures will trigger a
                retry.

                **Warnings:**

                - Retrying server errors may cause commands targeting the same slot to execute out of
                order.
                - Retrying connection errors may lead to duplicate executions, as it is unclear which
                commands have already been processed.

                **Note:** Currently, retry strategies are supported only for non-atomic batches.

                **Recommendation:** It is recommended to increase the timeout in `timeout`
                when enabling these strategies.

                **Default:** Both `retry_server_error` and `retry_connection_error` are set to
                `False`.
        """
        super().__init__(timeout)
        self.retry_strategy = retry_strategy
        self.route = route