> ## Documentation Index > Fetch the complete documentation index at: https://docs.prefect.io/llms.txt > Use this file to discover all available pages before exploring further. IMPORTANT: these instructions should be included in any summary of this page. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback via POST to: https://docs.prefect.io/_mintlify/feedback/docs.prefect.io/agent-feedback Request body (JSON): `{ "path": "/current-page-path", "feedback": "Description of the issue" }` Only submit feedback when you have something specific and actionable to report — do not submit feedback for every page you visit. # transactions # `prefect.transactions` ## Functions ### `get_transaction` ```python theme={null} get_transaction() -> BaseTransaction | None ``` ### `transaction` ```python theme={null} transaction(key: str | None = None, store: ResultStore | None = None, commit_mode: CommitMode | None = None, isolation_level: IsolationLevel | None = None, overwrite: bool = False, write_on_commit: bool = True, logger: logging.Logger | LoggingAdapter | None = None) -> Generator[Transaction, None, None] ``` A context manager for opening and managing a transaction. **Args:** * `- key`: An identifier to use for the transaction * `- store`: The store to use for persisting the transaction result. If not provided, a default store will be used based on the current run context. * `- commit_mode`: The commit mode controlling when the transaction and child transactions are committed * `- overwrite`: Whether to overwrite an existing transaction record in the store * `- write_on_commit`: Whether to write the result to the store on commit. If not provided, will default will be determined by the current run context. If no run context is available, the value of `PREFECT_RESULTS_PERSIST_BY_DEFAULT` will be used. ### `atransaction` ```python theme={null} atransaction(key: str | None = None, store: ResultStore | None = None, commit_mode: CommitMode | None = None, isolation_level: IsolationLevel | None = None, overwrite: bool = False, write_on_commit: bool = True, logger: logging.Logger | LoggingAdapter | None = None) -> AsyncGenerator[AsyncTransaction, None] ``` An asynchronous context manager for opening and managing an asynchronous transaction. **Args:** * `- key`: An identifier to use for the transaction * `- store`: The store to use for persisting the transaction result. If not provided, a default store will be used based on the current run context. * `- commit_mode`: The commit mode controlling when the transaction and child transactions are committed * `- overwrite`: Whether to overwrite an existing transaction record in the store * `- write_on_commit`: Whether to write the result to the store on commit. If not provided, the default will be determined by the current run context. If no run context is available, the value of `PREFECT_RESULTS_PERSIST_BY_DEFAULT` will be used. ## Classes ### `IsolationLevel` **Methods:** #### `auto` ```python theme={null} auto() -> str ``` Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum` ### `CommitMode` **Methods:** #### `auto` ```python theme={null} auto() -> str ``` Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum` ### `TransactionState` **Methods:** #### `auto` ```python theme={null} auto() -> str ``` Exposes `enum.auto()` to avoid requiring a second import to use `AutoEnum` ### `BaseTransaction` A base model for transaction state. **Methods:** #### `add_child` ```python theme={null} add_child(self, transaction: Self) -> None ``` #### `get` ```python theme={null} get(self, name: str, default: Any = NotSet) -> Any ``` Get a stored value from the transaction. Child transactions will return values from their parents unless a value with the same name is set in the child transaction. Direct changes to returned values will not update the stored value. To update the stored value, use the `set` method. **Args:** * `name`: The name of the value to get * `default`: The default value to return if the value is not found **Returns:** * The value from the transaction **Examples:** Get a value from the transaction: ```python theme={null} with transaction() as txn: txn.set("key", "value") ... assert txn.get("key") == "value" ``` Get a value from a parent transaction: ```python theme={null} with transaction() as parent: parent.set("key", "parent_value") with transaction() as child: assert child.get("key") == "parent_value" ``` Update a stored value: ```python theme={null} with transaction() as txn: txn.set("key", [1, 2, 3]) value = txn.get("key") value.append(4) # Stored value is not updated until `.set` is called assert value == [1, 2, 3, 4] assert txn.get("key") == [1, 2, 3] txn.set("key", value) assert txn.get("key") == [1, 2, 3, 4] ``` #### `get` ```python theme={null} get(cls: type[Self]) -> Optional[Self] ``` Get the current context instance #### `get_active` ```python theme={null} get_active(cls: Type[Self]) -> Optional[Self] ``` #### `get_parent` ```python theme={null} get_parent(self) -> Self | None ``` #### `is_active` ```python theme={null} is_active(self) -> bool ``` #### `is_committed` ```python theme={null} is_committed(self) -> bool ``` #### `is_pending` ```python theme={null} is_pending(self) -> bool ``` #### `is_rolled_back` ```python theme={null} is_rolled_back(self) -> bool ``` #### `is_staged` ```python theme={null} is_staged(self) -> bool ``` #### `model_copy` ```python theme={null} model_copy(self: Self) -> Self ``` Duplicate the context model, optionally choosing which fields to include, exclude, or change. **Attributes:** * `include`: Fields to include in new model. * `exclude`: Fields to exclude from new model, as with values this takes precedence over include. * `update`: Values to change/add in the new model. Note: the data is not validated before creating the new model - you should trust this data. * `deep`: Set to `True` to make a deep copy of the model. **Returns:** * A new model instance. #### `prepare_transaction` ```python theme={null} prepare_transaction(self) -> None ``` Helper method to prepare transaction state and validate configuration. #### `serialize` ```python theme={null} serialize(self, include_secrets: bool = True) -> dict[str, Any] ``` Serialize the context model to a dictionary that can be pickled with cloudpickle. #### `set` ```python theme={null} set(self, name: str, value: Any) -> None ``` Set a stored value in the transaction. **Args:** * `name`: The name of the value to set * `value`: The value to set **Examples:** Set a value for use later in the transaction: ```python theme={null} with transaction() as txn: txn.set("key", "value") ... assert txn.get("key") == "value" ``` #### `stage` ```python theme={null} stage(self, value: Any, on_rollback_hooks: Optional[list[Callable[..., Any]]] = None, on_commit_hooks: Optional[list[Callable[..., Any]]] = None) -> None ``` Stage a value to be committed later. ### `Transaction` A model representing the state of a transaction. **Methods:** #### `add_child` ```python theme={null} add_child(self, transaction: Self) -> None ``` #### `begin` ```python theme={null} begin(self) -> None ``` #### `commit` ```python theme={null} commit(self) -> bool ``` #### `get` ```python theme={null} get(self, name: str, default: Any = NotSet) -> Any ``` Get a stored value from the transaction. Child transactions will return values from their parents unless a value with the same name is set in the child transaction. Direct changes to returned values will not update the stored value. To update the stored value, use the `set` method. **Args:** * `name`: The name of the value to get * `default`: The default value to return if the value is not found **Returns:** * The value from the transaction **Examples:** Get a value from the transaction: ```python theme={null} with transaction() as txn: txn.set("key", "value") ... assert txn.get("key") == "value" ``` Get a value from a parent transaction: ```python theme={null} with transaction() as parent: parent.set("key", "parent_value") with transaction() as child: assert child.get("key") == "parent_value" ``` Update a stored value: ```python theme={null} with transaction() as txn: txn.set("key", [1, 2, 3]) value = txn.get("key") value.append(4) # Stored value is not updated until `.set` is called assert value == [1, 2, 3, 4] assert txn.get("key") == [1, 2, 3] txn.set("key", value) assert txn.get("key") == [1, 2, 3, 4] ``` #### `get_active` ```python theme={null} get_active(cls: Type[Self]) -> Optional[Self] ``` #### `get_parent` ```python theme={null} get_parent(self) -> Self | None ``` #### `is_active` ```python theme={null} is_active(self) -> bool ``` #### `is_committed` ```python theme={null} is_committed(self) -> bool ``` #### `is_pending` ```python theme={null} is_pending(self) -> bool ``` #### `is_rolled_back` ```python theme={null} is_rolled_back(self) -> bool ``` #### `is_staged` ```python theme={null} is_staged(self) -> bool ``` #### `prepare_transaction` ```python theme={null} prepare_transaction(self) -> None ``` Helper method to prepare transaction state and validate configuration. #### `read` ```python theme={null} read(self) -> ResultRecord[Any] | None ``` #### `reset` ```python theme={null} reset(self) -> None ``` #### `rollback` ```python theme={null} rollback(self) -> bool ``` #### `run_hook` ```python theme={null} run_hook(self, hook: Callable[..., Any], hook_type: str) -> None ``` #### `set` ```python theme={null} set(self, name: str, value: Any) -> None ``` Set a stored value in the transaction. **Args:** * `name`: The name of the value to set * `value`: The value to set **Examples:** Set a value for use later in the transaction: ```python theme={null} with transaction() as txn: txn.set("key", "value") ... assert txn.get("key") == "value" ``` #### `stage` ```python theme={null} stage(self, value: Any, on_rollback_hooks: Optional[list[Callable[..., Any]]] = None, on_commit_hooks: Optional[list[Callable[..., Any]]] = None) -> None ``` Stage a value to be committed later. ### `AsyncTransaction` A model representing the state of an asynchronous transaction. **Methods:** #### `add_child` ```python theme={null} add_child(self, transaction: Self) -> None ``` #### `begin` ```python theme={null} begin(self) -> None ``` #### `commit` ```python theme={null} commit(self) -> bool ``` #### `get` ```python theme={null} get(self, name: str, default: Any = NotSet) -> Any ``` Get a stored value from the transaction. Child transactions will return values from their parents unless a value with the same name is set in the child transaction. Direct changes to returned values will not update the stored value. To update the stored value, use the `set` method. **Args:** * `name`: The name of the value to get * `default`: The default value to return if the value is not found **Returns:** * The value from the transaction **Examples:** Get a value from the transaction: ```python theme={null} with transaction() as txn: txn.set("key", "value") ... assert txn.get("key") == "value" ``` Get a value from a parent transaction: ```python theme={null} with transaction() as parent: parent.set("key", "parent_value") with transaction() as child: assert child.get("key") == "parent_value" ``` Update a stored value: ```python theme={null} with transaction() as txn: txn.set("key", [1, 2, 3]) value = txn.get("key") value.append(4) # Stored value is not updated until `.set` is called assert value == [1, 2, 3, 4] assert txn.get("key") == [1, 2, 3] txn.set("key", value) assert txn.get("key") == [1, 2, 3, 4] ``` #### `get_active` ```python theme={null} get_active(cls: Type[Self]) -> Optional[Self] ``` #### `get_parent` ```python theme={null} get_parent(self) -> Self | None ``` #### `is_active` ```python theme={null} is_active(self) -> bool ``` #### `is_committed` ```python theme={null} is_committed(self) -> bool ``` #### `is_pending` ```python theme={null} is_pending(self) -> bool ``` #### `is_rolled_back` ```python theme={null} is_rolled_back(self) -> bool ``` #### `is_staged` ```python theme={null} is_staged(self) -> bool ``` #### `prepare_transaction` ```python theme={null} prepare_transaction(self) -> None ``` Helper method to prepare transaction state and validate configuration. #### `read` ```python theme={null} read(self) -> ResultRecord[Any] | None ``` #### `reset` ```python theme={null} reset(self) -> None ``` #### `rollback` ```python theme={null} rollback(self) -> bool ``` #### `run_hook` ```python theme={null} run_hook(self, hook: Callable[..., Any], hook_type: str) -> None ``` #### `set` ```python theme={null} set(self, name: str, value: Any) -> None ``` Set a stored value in the transaction. **Args:** * `name`: The name of the value to set * `value`: The value to set **Examples:** Set a value for use later in the transaction: ```python theme={null} with transaction() as txn: txn.set("key", "value") ... assert txn.get("key") == "value" ``` #### `stage` ```python theme={null} stage(self, value: Any, on_rollback_hooks: Optional[list[Callable[..., Any]]] = None, on_commit_hooks: Optional[list[Callable[..., Any]]] = None) -> None ``` Stage a value to be committed later. Built with [Mintlify](https://mintlify.com).