1515 from databricks .sql .client import Cursor
1616
1717from databricks .sql .thrift_api .TCLIService import ttypes
18- from databricks .sql .backend .types import (
19- SessionId ,
20- CommandId ,
21- CommandState ,
22- ExecuteResponse ,
23- )
24- from databricks .sql .types import SSLOptions
18+ from databricks .sql .backend .types import SessionId , CommandId , CommandState
2519
2620# Forward reference for type hints
2721from typing import TYPE_CHECKING
@@ -92,6 +86,34 @@ def execute_command(
9286 async_op : bool ,
9387 enforce_embedded_schema_correctness : bool ,
9488 ) -> Union ["ResultSet" , None ]:
89+ """
90+ Executes a SQL command or query within the specified session.
91+
92+ This method sends a SQL command to the server for execution and handles
93+ the response. It can operate in both synchronous and asynchronous modes.
94+
95+ Args:
96+ operation: The SQL command or query to execute
97+ session_id: The session identifier in which to execute the command
98+ max_rows: Maximum number of rows to fetch in a single fetch batch
99+ max_bytes: Maximum number of bytes to fetch in a single fetch batch
100+ lz4_compression: Whether to use LZ4 compression for result data
101+ cursor: The cursor object that will handle the results
102+ use_cloud_fetch: Whether to use cloud fetch for retrieving large result sets
103+ parameters: List of parameters to bind to the query
104+ async_op: Whether to execute the command asynchronously
105+ enforce_embedded_schema_correctness: Whether to enforce schema correctness
106+
107+ Returns:
108+ If async_op is False, returns a ResultSet object containing the
109+ query results and metadata. If async_op is True, returns None and the
110+ results must be fetched later using get_execution_result().
111+
112+ Raises:
113+ ValueError: If the session ID is invalid
114+ OperationalError: If there's an error executing the command
115+ ServerOperationError: If the server encounters an error during execution
116+ """
95117 pass
96118
97119 @abstractmethod
@@ -113,10 +135,40 @@ def cancel_command(self, command_id: CommandId) -> None:
113135
114136 @abstractmethod
115137 def close_command (self , command_id : CommandId ) -> None :
138+ """
139+ Closes a command and releases associated resources.
140+
141+ This method informs the server that the client is done with the command
142+ and any resources associated with it can be released.
143+
144+ Args:
145+ command_id: The command identifier to close
146+
147+ Raises:
148+ ValueError: If the command ID is invalid
149+ OperationalError: If there's an error closing the command
150+ """
116151 pass
117152
118153 @abstractmethod
119154 def get_query_state (self , command_id : CommandId ) -> CommandState :
155+ """
156+ Gets the current state of a query or command.
157+
158+ This method retrieves the current execution state of a command from the server.
159+
160+ Args:
161+ command_id: The command identifier to check
162+
163+ Returns:
164+ CommandState: The current state of the command
165+
166+ Raises:
167+ ValueError: If the command ID is invalid
168+ OperationalError: If there's an error retrieving the state
169+ ServerOperationError: If the command is in an error state
170+ DatabaseError: If the command has been closed unexpectedly
171+ """
120172 pass
121173
122174 @abstractmethod
@@ -125,6 +177,23 @@ def get_execution_result(
125177 command_id : CommandId ,
126178 cursor : "Cursor" ,
127179 ) -> "ResultSet" :
180+ """
181+ Retrieves the results of a previously executed command.
182+
183+ This method fetches the results of a command that was executed asynchronously
184+ or retrieves additional results from a command that has more rows available.
185+
186+ Args:
187+ command_id: The command identifier for which to retrieve results
188+ cursor: The cursor object that will handle the results
189+
190+ Returns:
191+ ResultSet: An object containing the query results and metadata
192+
193+ Raises:
194+ ValueError: If the command ID is invalid
195+ OperationalError: If there's an error retrieving the results
196+ """
128197 pass
129198
130199 # == Metadata Operations ==
@@ -136,6 +205,25 @@ def get_catalogs(
136205 max_bytes : int ,
137206 cursor : "Cursor" ,
138207 ) -> "ResultSet" :
208+ """
209+ Retrieves a list of available catalogs.
210+
211+ This method fetches metadata about all catalogs available in the current
212+ session's context.
213+
214+ Args:
215+ session_id: The session identifier
216+ max_rows: Maximum number of rows to fetch in a single batch
217+ max_bytes: Maximum number of bytes to fetch in a single batch
218+ cursor: The cursor object that will handle the results
219+
220+ Returns:
221+ ResultSet: An object containing the catalog metadata
222+
223+ Raises:
224+ ValueError: If the session ID is invalid
225+ OperationalError: If there's an error retrieving the catalogs
226+ """
139227 pass
140228
141229 @abstractmethod
@@ -148,6 +236,27 @@ def get_schemas(
148236 catalog_name : Optional [str ] = None ,
149237 schema_name : Optional [str ] = None ,
150238 ) -> "ResultSet" :
239+ """
240+ Retrieves a list of schemas, optionally filtered by catalog and schema name patterns.
241+
242+ This method fetches metadata about schemas available in the specified catalog
243+ or all catalogs if no catalog is specified.
244+
245+ Args:
246+ session_id: The session identifier
247+ max_rows: Maximum number of rows to fetch in a single batch
248+ max_bytes: Maximum number of bytes to fetch in a single batch
249+ cursor: The cursor object that will handle the results
250+ catalog_name: Optional catalog name pattern to filter by
251+ schema_name: Optional schema name pattern to filter by
252+
253+ Returns:
254+ ResultSet: An object containing the schema metadata
255+
256+ Raises:
257+ ValueError: If the session ID is invalid
258+ OperationalError: If there's an error retrieving the schemas
259+ """
151260 pass
152261
153262 @abstractmethod
@@ -162,6 +271,29 @@ def get_tables(
162271 table_name : Optional [str ] = None ,
163272 table_types : Optional [List [str ]] = None ,
164273 ) -> "ResultSet" :
274+ """
275+ Retrieves a list of tables, optionally filtered by catalog, schema, table name, and table types.
276+
277+ This method fetches metadata about tables available in the specified catalog
278+ and schema, or all catalogs and schemas if not specified.
279+
280+ Args:
281+ session_id: The session identifier
282+ max_rows: Maximum number of rows to fetch in a single batch
283+ max_bytes: Maximum number of bytes to fetch in a single batch
284+ cursor: The cursor object that will handle the results
285+ catalog_name: Optional catalog name pattern to filter by
286+ schema_name: Optional schema name pattern to filter by
287+ table_name: Optional table name pattern to filter by
288+ table_types: Optional list of table types to filter by (e.g., ['TABLE', 'VIEW'])
289+
290+ Returns:
291+ ResultSet: An object containing the table metadata
292+
293+ Raises:
294+ ValueError: If the session ID is invalid
295+ OperationalError: If there's an error retrieving the tables
296+ """
165297 pass
166298
167299 @abstractmethod
0 commit comments