diff --git a/ydb/query/base.py b/ydb/query/base.py index dcb56ca6..e08d9f52 100644 --- a/ydb/query/base.py +++ b/ydb/query/base.py @@ -103,7 +103,8 @@ def __init__(self, driver: SupportedDriverType, settings: Optional[QueryClientSe @abc.abstractmethod def create(self) -> "IQuerySession": - """ + """WARNING: This API is experimental and could be changed. + Creates a Session of Query Service on server side and attaches it. :return: Session object. @@ -112,7 +113,8 @@ def create(self) -> "IQuerySession": @abc.abstractmethod def delete(self) -> None: - """ + """WARNING: This API is experimental and could be changed. + Deletes a Session of Query Service on server side and releases resources. :return: None @@ -121,7 +123,8 @@ def delete(self) -> None: @abc.abstractmethod def transaction(self, tx_mode: Optional[BaseQueryTxMode] = None) -> "IQueryTxContext": - """ + """WARNING: This API is experimental and could be changed. + Creates a transaction context manager with specified transaction mode. :param tx_mode: Transaction mode, which is a one from the following choises: @@ -143,7 +146,8 @@ def execute( parameters: Optional[dict] = None, concurrent_result_sets: Optional[bool] = False, ) -> Iterator: - """ + """WARNING: This API is experimental and could be changed. + Sends a query to Query Service :param query: (YQL or SQL text) to be executed. :param syntax: Syntax of the query, which is a one from the following choises: @@ -235,7 +239,8 @@ def tx_id(self) -> Optional[str]: @abc.abstractmethod def begin(self, settings: Optional[QueryClientSettings] = None) -> None: - """ + """WARNING: This API is experimental and could be changed. + Explicitly begins a transaction :param settings: A request settings @@ -246,7 +251,8 @@ def begin(self, settings: Optional[QueryClientSettings] = None) -> None: @abc.abstractmethod def commit(self, settings: Optional[QueryClientSettings] = None) -> None: - """ + """WARNING: This API is experimental and could be changed. + Calls commit on a transaction if it is open. If transaction execution failed then this method raises PreconditionFailed. @@ -258,7 +264,8 @@ def commit(self, settings: Optional[QueryClientSettings] = None) -> None: @abc.abstractmethod def rollback(self, settings: Optional[QueryClientSettings] = None) -> None: - """ + """WARNING: This API is experimental and could be changed. + Calls rollback on a transaction if it is open. If transaction execution failed then this method raises PreconditionFailed. @@ -278,7 +285,8 @@ def execute( parameters: Optional[dict] = None, concurrent_result_sets: Optional[bool] = False, ) -> Iterator: - """ + """WARNING: This API is experimental and could be changed. + Sends a query to Query Service :param query: (YQL or SQL text) to be executed. :param commit_tx: A special flag that allows transaction commit. diff --git a/ydb/query/pool.py b/ydb/query/pool.py index bddd666a..e7514cdf 100644 --- a/ydb/query/pool.py +++ b/ydb/query/pool.py @@ -30,12 +30,15 @@ def __init__(self, driver: base.SupportedDriverType): self._driver = driver def checkout(self) -> "SimpleQuerySessionCheckout": - """Return a Session context manager, that opens session on enter and closes session on exit.""" + """WARNING: This API is experimental and could be changed. + Return a Session context manager, that opens session on enter and closes session on exit. + """ return SimpleQuerySessionCheckout(self) def retry_operation_sync(self, callee: Callable, retry_settings: Optional[RetrySettings] = None, *args, **kwargs): - """Special interface to execute a bunch of commands with session in a safe, retriable way. + """WARNING: This API is experimental and could be changed. + Special interface to execute a bunch of commands with session in a safe, retriable way. :param callee: A function, that works with session. :param retry_settings: RetrySettings object. @@ -54,7 +57,8 @@ def wrapped_callee(): def execute_with_retries( self, query: str, retry_settings: Optional[RetrySettings] = None, *args, **kwargs ) -> List[convert.ResultSet]: - """Special interface to execute a one-shot queries in a safe, retriable way. + """WARNING: This API is experimental and could be changed. + Special interface to execute a one-shot queries in a safe, retriable way. Note: this method loads all data from stream before return, do not use this method with huge read queries. diff --git a/ydb/query/session.py b/ydb/query/session.py index 5b9c00ed..d6034d34 100644 --- a/ydb/query/session.py +++ b/ydb/query/session.py @@ -227,7 +227,8 @@ def _check_session_status_loop(self, status_stream: _utilities.SyncResponseItera pass def delete(self) -> None: - """ + """WARNING: This API is experimental and could be changed. + Deletes a Session of Query Service on server side and releases resources. :return: None @@ -240,7 +241,8 @@ def delete(self) -> None: self._stream.cancel() def create(self) -> "QuerySessionSync": - """ + """WARNING: This API is experimental and could be changed. + Creates a Session of Query Service on server side and attaches it. :return: QuerySessionSync object. @@ -255,7 +257,8 @@ def create(self) -> "QuerySessionSync": return self def transaction(self, tx_mode: Optional[base.BaseQueryTxMode] = None) -> base.IQueryTxContext: - """ + """WARNING: This API is experimental and could be changed. + Creates a transaction context manager with specified transaction mode. :param tx_mode: Transaction mode, which is a one from the following choises: 1) QuerySerializableReadWrite() which is default mode; @@ -285,7 +288,8 @@ def execute( parameters: dict = None, concurrent_result_sets: bool = False, ) -> base.SyncResponseContextIterator: - """ + """WARNING: This API is experimental and could be changed. + Sends a query to Query Service :param query: (YQL or SQL text) to be executed. :param syntax: Syntax of the query, which is a one from the following choises: diff --git a/ydb/query/transaction.py b/ydb/query/transaction.py index 6846b5a5..0a493202 100644 --- a/ydb/query/transaction.py +++ b/ydb/query/transaction.py @@ -314,7 +314,8 @@ def _move_to_commited(self) -> None: self._tx_state._change_state(QueryTxStateEnum.COMMITTED) def begin(self, settings: Optional[base.QueryClientSettings] = None) -> None: - """ + """WARNING: This API is experimental and could be changed. + Explicitly begins a transaction :param settings: A request settings @@ -326,7 +327,8 @@ def begin(self, settings: Optional[base.QueryClientSettings] = None) -> None: self._begin_call(settings) def commit(self, settings: Optional[base.QueryClientSettings] = None) -> None: - """ + """WARNING: This API is experimental and could be changed. + Calls commit on a transaction if it is open otherwise is no-op. If transaction execution failed then this method raises PreconditionFailed. @@ -369,7 +371,24 @@ def execute( parameters: Optional[dict] = None, concurrent_result_sets: Optional[bool] = False, ) -> base.SyncResponseContextIterator: - + """WARNING: This API is experimental and could be changed. + + Sends a query to Query Service + :param query: (YQL or SQL text) to be executed. + :param commit_tx: A special flag that allows transaction commit. + :param syntax: Syntax of the query, which is a one from the following choises: + 1) QuerySyntax.YQL_V1, which is default; + 2) QuerySyntax.PG. + :param exec_mode: Exec mode of the query, which is a one from the following choises: + 1) QueryExecMode.EXECUTE, which is default; + 2) QueryExecMode.EXPLAIN; + 3) QueryExecMode.VALIDATE; + 4) QueryExecMode.PARSE. + :param parameters: dict with parameters and YDB types; + :param concurrent_result_sets: A flag to allow YDB mix parts of different result sets. Default is False; + + :return: Iterator with result sets + """ self._ensure_prev_stream_finished() self._tx_state._check_tx_ready_to_use()