# Advanced Usage

## Transaction Options

Transactions can be customized with different options:

## Class: TransactionOptions

```py
TransactionOptions(isolation = IsolationLevel.Serializable, readonly = False, deferrable = False)
```

##### Parameters

- **isolation** ([*IsolationLevel*](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.IsolationLevel)) – transaction isolation level

- **readonly** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – if true the transaction will be readonly
- **deferrable** ([*bool*](https://docs.python.org/3/library/functions.html#bool)) – if true the transaction will be deferrable





## Method: TransactionOptions.defaults()

```py
TransactionOptions.defaults()
```

Returns the default [`TransactionOptions`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.TransactionOptions).



## Class: IsolationLevel

```py
IsolationLevel
```

Isolation level for transaction

## Attribute: IsolationLevel.Serializable

```py
IsolationLevel.Serializable
```

Serializable isolation level


## Attribute: IsolationLevel.RepeatableRead

```py
IsolationLevel.RepeatableRead
```

Repeatable read isolation level (supported in read-only transactions)


## Attribute: IsolationLevel.PreferRepeatableRead

```py
IsolationLevel.PreferRepeatableRead
```

Uses repeatable read isolation level if server analysis concludes that it is supported for a given query. Otherwise, uses serializable isolation level.



[`TransactionOptions`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.TransactionOptions) can be set on [`Client`](https://docs.geldata.com/reference/using/python/client.md#gel.Client) or [`AsyncIOClient`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient) using one of these methods:

- [`gel.Client.with_transaction_options()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_transaction_options)
- [`gel.AsyncIOClient.with_transaction_options()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_transaction_options)


These methods return a "shallow copy" of the current client object with modified transaction options. Both `self` and the returned object can be used, but different transaction options will applied respectively.

Transaction options are used by the future calls to the method [`gel.Client.transaction()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.transaction) or [`gel.AsyncIOClient.transaction()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.transaction).

## Retry Options

Individual EdgeQL commands or whole transaction blocks are automatically retried on retryable errors. By default, gel-python will try at most 3 times, with an exponential backoff time interval starting from 100ms, plus a random hash under 100ms.

Retry rules can be granularly customized with different retry options:

## Class: RetryOptions

```py
RetryOptions(attempts, backoff = default_backoff)
```

##### Parameters

- **attempts** ([*int*](https://docs.python.org/3/library/functions.html#int)) – the default number of attempts
- **backoff** (*Callable**[**[*[*int*](https://docs.python.org/3/library/functions.html#int)*]**, **Union**[*[*float*](https://docs.python.org/3/library/functions.html#float)*, *[*int*](https://docs.python.org/3/library/functions.html#int)*]**]*) – the default backoff function






## Method: RetryOptions.with_rule()

```py
RetryOptions.with_rule(condition, attempts = None, backoff = None)
```

Adds a backoff rule for a particular condition

##### Parameters

- **condition** ([*RetryCondition*](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.RetryCondition)) – condition that will trigger this rule

- **attempts** ([*int*](https://docs.python.org/3/library/functions.html#int)) – number of times to retry
- **backoff** (*Callable**[**[*[*int*](https://docs.python.org/3/library/functions.html#int)*]**, **Union**[*[*float*](https://docs.python.org/3/library/functions.html#float)*, *[*int*](https://docs.python.org/3/library/functions.html#int)*]**]*) – function taking the current attempt number and returning the number of seconds to wait before the next attempt







## Method: RetryOptions.defaults()

```py
RetryOptions.defaults()
```

Returns the default [`RetryOptions`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.RetryOptions).



## Class: RetryCondition

```py
RetryCondition
```

Specific condition to retry on for fine-grained control

## Attribute: RetryCondition.TransactionConflict

```py
RetryCondition.TransactionConflict
```

Triggered when a TransactionConflictError occurs.


## Attribute: RetryCondition.NetworkError

```py
RetryCondition.NetworkError
```

Triggered when a ClientError occurs.



[`RetryOptions`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.RetryOptions) can be set on [`Client`](https://docs.geldata.com/reference/using/python/client.md#gel.Client) or [`AsyncIOClient`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient) using one of these methods:

- [`gel.Client.with_retry_options()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_retry_options)
- [`gel.AsyncIOClient.with_retry_options()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_retry_options)

These methods return a "shallow copy" of the current client object with modified retry options. Both `self` and the returned object can be used, but different retry options will applied respectively.

## State

State is an execution context that affects the execution of EdgeQL commands in different ways: default module, module aliases, session config and global values.

## Class: State

```py
State(default_module = None, module_aliases = {}, config = {}, globals_ = {})
```

##### Parameters

- **default_module** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)* or *[*None*](https://docs.python.org/3/library/constants.html#None)) – The *default module* that the future commands will be executed with. `None` means the default *default module* on the server-side, which is usually just `default`.

- **module_aliases** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*str*](https://docs.python.org/3/library/stdtypes.html#str)*]*) – Module aliases mapping of alias -> target module.

- **config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*object*](https://docs.python.org/3/library/functions.html#object)*]*) – Non system-level config settings mapping of config name -> config value.
  
  For available configuration parameters refer to the [Config documentation](https://docs.geldata.com/reference/stdlib/cfg.md#ref-std-cfg).

- **globals** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*object*](https://docs.python.org/3/library/functions.html#object)*]*) – Global values mapping of global name -> global value.
  
  > Note: The global name can be either a qualified name like `my_mod::glob2`, or a simple name under the default module. Simple names will be prefixed with the default module, while module aliases in qualified names - if any - will be resolved into actual module names.






## Method: State.with_default_module()

```py
State.with_default_module(module = None)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy with adjusted default module.

> Note: This will not affect the globals that are already stored in this state using simple names, because their names were resolved before this call to `with_default_module()`, which affects only the future calls to the [`with_globals()`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State.with_globals) method.

This is equivalent to using the `set module` command, or using the `reset module` command when giving `None`.

##### Parameters

**module** ([*str*](https://docs.python.org/3/library/stdtypes.html#str)* or *[*None*](https://docs.python.org/3/library/constants.html#None)) – Adjust the *default module*. If `module` is `None`, the *default module* will be reset to default.






## Method: State.with_module_aliases()

```py
State.with_module_aliases(aliases_dict = None, /, ** aliases)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy with adjusted module aliases.

> Note: This will not affect the globals that are already stored in this state using module aliases, because their names were resolved before this call to `with_module_aliases()`, which affects only the future calls to the [`with_globals()`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State.with_globals) method.

This is equivalent to using the `set alias` command.

##### Parameters

- **aliases_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*str*](https://docs.python.org/3/library/stdtypes.html#str)*] or *[*None*](https://docs.python.org/3/library/constants.html#None)) – Adjust the module aliases by merging with the given alias -> target module mapping. This is an optional positional-only argument.

- **aliases** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*str*](https://docs.python.org/3/library/stdtypes.html#str)*]*) – Adjust the module aliases by merging with the given alias -> target module mapping, after applying `aliases_dict` if set.







## Method: State.without_module_aliases()

```py
State.without_module_aliases(* aliases)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy without specified module aliases.

> Note: This will not affect the globals that are already stored in this state using module aliases, because their names were resolved before this call to `without_module_aliases()`, which affects only the future calls to the [`with_globals()`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State.with_globals) method.

This is equivalent to using the `reset alias` command.

##### Parameters

**aliases** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*]*) – Adjust the module aliases by dropping the specified aliases if they were set, no errors will be raised if they weren't.

If no aliases were given, all module aliases will be dropped.








## Method: State.with_config()

```py
State.with_config(config_dict = None, /, ** config)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy with adjusted session config.

This is equivalent to using the `configure session set` command.

##### Parameters

- **config_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*object*](https://docs.python.org/3/library/functions.html#object)*] or *[*None*](https://docs.python.org/3/library/constants.html#None)) – Adjust the config settings by merging with the given config name -> config value mapping. This is an optional positional-only argument.

- **config** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*object*](https://docs.python.org/3/library/functions.html#object)*]*) – Adjust the config settings by merging with the given config name -> config value mapping, after applying `config_dict` if set.







## Method: State.without_config()

```py
State.without_config(* config_names)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy without specified session config.

This is equivalent to using the `configure session reset` command.

##### Parameters

**config_names** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*]*) – Adjust the config settings by resetting the specified config to default if they were set, no errors will be raised if they weren't.

If no names were given, all session config will be reset.








## Method: State.with_globals()

```py
State.with_globals(globals_dict = None, /, ** globals_)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy with adjusted global values.

> Note: The globals are stored with their names resolved into the actual fully-qualified names using the current default module and module aliases set on this state.

This is equivalent to using the `set global` command.

##### Parameters

- **globals_dict** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*object*](https://docs.python.org/3/library/functions.html#object)*] or *[*None*](https://docs.python.org/3/library/constants.html#None)) – Adjust the global values by merging with the given global name -> global value mapping. This is an optional positional-only argument.

- **globals** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*, *[*object*](https://docs.python.org/3/library/functions.html#object)*]*) – Adjust the global values by merging with the given global name -> global value mapping, after applying `globals_dict` if set.







## Method: State.without_globals()

```py
State.without_globals(* global_names)
```

Returns a new [`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) copy without specified globals.

This is equivalent to using the `reset global` command.

##### Parameters

**global_names** ([*tuple*](https://docs.python.org/3/library/stdtypes.html#tuple)*[*[*str*](https://docs.python.org/3/library/stdtypes.html#str)*]*) – Adjust the globals by resetting the specified globals to default if they were set, no errors will be raised if they weren't.

If no names were given, all globals will be reset.









[`State`](https://docs.geldata.com/reference/using/python/api/advanced.md#gel.State) can be set on [`Client`](https://docs.geldata.com/reference/using/python/client.md#gel.Client) or [`AsyncIOClient`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient) using one of these methods:

- [`gel.Client.with_state()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_state)
- [`gel.AsyncIOClient.with_state()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_state)

These methods return a "shallow copy" of the current client object with modified state, affecting all future commands executed using the returned copy. Both `self` and the returned object can be used, but different state will applied respectively.

Alternatively, shortcuts are available on client objects:

- [`gel.Client.with_default_module()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_default_module)
- [`gel.Client.with_module_aliases()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_module_aliases)
- [`gel.Client.without_module_aliases()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.without_module_aliases)
- [`gel.Client.with_config()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_config)
- [`gel.Client.without_config()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.without_config)
- [`gel.Client.with_globals()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.with_globals)
- [`gel.Client.without_globals()`](https://docs.geldata.com/reference/using/python/client.md#gel.Client.without_globals)
- [`gel.AsyncIOClient.with_default_module()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_default_module)
- [`gel.AsyncIOClient.with_module_aliases()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_module_aliases)
- [`gel.AsyncIOClient.without_module_aliases()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.without_module_aliases)

- [`gel.AsyncIOClient.with_config()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_config)
- [`gel.AsyncIOClient.without_config()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.without_config)
- [`gel.AsyncIOClient.with_globals()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.with_globals)
- [`gel.AsyncIOClient.without_globals()`](https://docs.geldata.com/reference/using/python/client.md#gel.AsyncIOClient.without_globals)

They work the same way as `with_state`, and adjusts the corresponding state values.