Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commiteecc67d

Browse files
docstrings for DatabricksClient interface
Signed-off-by: varun-edachali-dbx <varun.edachali@databricks.com>
1 parent8da84e8 commiteecc67d

File tree

1 file changed

+279
-1
lines changed

1 file changed

+279
-1
lines changed

‎src/databricks/sql/backend/databricks_client.py‎

Lines changed: 279 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,15 @@
1+
"""
2+
Abstract client interface for interacting with Databricks SQL services.
3+
4+
Implementations of this class are responsible for:
5+
- Managing connections to Databricks SQL services
6+
- Handling authentication
7+
- Executing SQL queries and commands
8+
- Retrieving query results
9+
- Fetching metadata about catalogs, schemas, tables, and columns
10+
- Managing error handling and retries
11+
"""
12+
113
fromabcimportABC,abstractmethod
214
fromtypingimportDict,Tuple,List,Optional,Any,Union
315

@@ -16,10 +28,42 @@ def open_session(
1628
catalog:Optional[str],
1729
schema:Optional[str],
1830
)->SessionId:
31+
"""
32+
Opens a new session with the Databricks SQL service.
33+
34+
This method establishes a new session with the server and returns a session
35+
identifier that can be used for subsequent operations.
36+
37+
Args:
38+
session_configuration: Optional dictionary of configuration parameters for the session
39+
catalog: Optional catalog name to use as the initial catalog for the session
40+
schema: Optional schema name to use as the initial schema for the session
41+
42+
Returns:
43+
SessionId: A session identifier object that can be used for subsequent operations
44+
45+
Raises:
46+
Error: If the session configuration is invalid
47+
OperationalError: If there's an error establishing the session
48+
InvalidServerResponseError: If the server response is invalid or unexpected
49+
"""
1950
pass
2051

2152
@abstractmethod
2253
defclose_session(self,session_id:SessionId)->None:
54+
"""
55+
Closes an existing session with the Databricks SQL service.
56+
57+
This method terminates the session identified by the given session ID and
58+
releases any resources associated with it.
59+
60+
Args:
61+
session_id: The session identifier returned by open_session()
62+
63+
Raises:
64+
ValueError: If the session ID is invalid
65+
OperationalError: If there's an error closing the session
66+
"""
2367
pass
2468

2569
# == Query Execution, Command Management ==
@@ -37,18 +81,92 @@ def execute_command(
3781
async_op:bool,
3882
enforce_embedded_schema_correctness:bool,
3983
)->Any:
84+
"""
85+
Executes a SQL command or query within the specified session.
86+
87+
This method sends a SQL command to the server for execution and handles
88+
the response. It can operate in both synchronous and asynchronous modes.
89+
90+
Args:
91+
operation: The SQL command or query to execute
92+
session_id: The session identifier in which to execute the command
93+
max_rows: Maximum number of rows to fetch in a single batch
94+
max_bytes: Maximum number of bytes to fetch in a single batch
95+
lz4_compression: Whether to use LZ4 compression for result data
96+
cursor: The cursor object that will handle the results
97+
use_cloud_fetch: Whether to use cloud fetch for retrieving large result sets
98+
parameters: List of parameters to bind to the query
99+
async_op: Whether to execute the command asynchronously
100+
enforce_embedded_schema_correctness: Whether to enforce schema correctness
101+
102+
Returns:
103+
If async_op is False, returns an ExecuteResponse object containing the
104+
query results and metadata. If async_op is True, returns None and the
105+
results must be fetched later using get_execution_result().
106+
107+
Raises:
108+
ValueError: If the session ID is invalid
109+
OperationalError: If there's an error executing the command
110+
ServerOperationError: If the server encounters an error during execution
111+
"""
40112
pass
41113

42114
@abstractmethod
43115
defcancel_command(self,command_id:CommandId)->None:
116+
"""
117+
Cancels a running command or query.
118+
119+
This method attempts to cancel a command that is currently being executed.
120+
It can be called from a different thread than the one executing the command.
121+
122+
Args:
123+
command_id: The command identifier to cancel
124+
125+
Raises:
126+
ValueError: If the command ID is invalid
127+
OperationalError: If there's an error canceling the command
128+
"""
44129
pass
45130

46131
@abstractmethod
47132
defclose_command(self,command_id:CommandId)->ttypes.TStatus:
133+
"""
134+
Closes a command and releases associated resources.
135+
136+
This method informs the server that the client is done with the command
137+
and any resources associated with it can be released.
138+
139+
Args:
140+
command_id: The command identifier to close
141+
142+
Returns:
143+
ttypes.TStatus: The status of the close operation
144+
145+
Raises:
146+
ValueError: If the command ID is invalid
147+
OperationalError: If there's an error closing the command
148+
"""
48149
pass
49150

50151
@abstractmethod
51152
defget_query_state(self,command_id:CommandId)->ttypes.TOperationState:
153+
"""
154+
Gets the current state of a query or command.
155+
156+
This method retrieves the current execution state of a command from the server.
157+
158+
Args:
159+
command_id: The command identifier to check
160+
161+
Returns:
162+
ttypes.TOperationState: The current state of the command
163+
164+
Raises:
165+
ValueError: If the command ID is invalid
166+
OperationalError: If there's an error retrieving the state
167+
ServerOperationError: If the command is in an error state
168+
DatabaseError: If the command has been closed unexpectedly
169+
"""
52170
pass
53171

54172
@abstractmethod
@@ -57,6 +175,23 @@ def get_execution_result(
57175
command_id:CommandId,
58176
cursor:Any,
59177
)->ExecuteResponse:
178+
"""
179+
Retrieves the results of a previously executed command.
180+
181+
This method fetches the results of a command that was executed asynchronously
182+
or retrieves additional results from a command that has more rows available.
183+
184+
Args:
185+
command_id: The command identifier for which to retrieve results
186+
cursor: The cursor object that will handle the results
187+
188+
Returns:
189+
ExecuteResponse: An object containing the query results and metadata
190+
191+
Raises:
192+
ValueError: If the command ID is invalid
193+
OperationalError: If there's an error retrieving the results
194+
"""
60195
pass
61196

62197
# == Metadata Operations ==
@@ -68,6 +203,25 @@ def get_catalogs(
68203
max_bytes:int,
69204
cursor:Any,
70205
)->Any:
206+
"""
207+
Retrieves a list of available catalogs.
208+
209+
This method fetches metadata about the catalogs that are available
210+
in the current session.
211+
212+
Args:
213+
session_id: The session identifier
214+
max_rows: Maximum number of rows to fetch in a single batch
215+
max_bytes: Maximum number of bytes to fetch in a single batch
216+
cursor: The cursor object that will handle the results
217+
218+
Returns:
219+
ExecuteResponse: An object containing the catalog metadata
220+
221+
Raises:
222+
ValueError: If the session ID is invalid
223+
OperationalError: If there's an error retrieving the catalogs
224+
"""
71225
pass
72226

73227
@abstractmethod
@@ -80,6 +234,27 @@ def get_schemas(
80234
catalog_name:Optional[str]=None,
81235
schema_name:Optional[str]=None,
82236
)->Any:
237+
"""
238+
Retrieves a list of available schemas.
239+
240+
This method fetches metadata about the schemas that are available
241+
in the specified catalog.
242+
243+
Args:
244+
session_id: The session identifier
245+
max_rows: Maximum number of rows to fetch in a single batch
246+
max_bytes: Maximum number of bytes to fetch in a single batch
247+
cursor: The cursor object that will handle the results
248+
catalog_name: Optional catalog name to filter schemas
249+
schema_name: Optional schema pattern to filter schemas by name
250+
251+
Returns:
252+
ExecuteResponse: An object containing the schema metadata
253+
254+
Raises:
255+
ValueError: If the session ID is invalid
256+
OperationalError: If there's an error retrieving the schemas
257+
"""
83258
pass
84259

85260
@abstractmethod
@@ -94,6 +269,29 @@ def get_tables(
94269
table_name:Optional[str]=None,
95270
table_types:Optional[List[str]]=None,
96271
)->Any:
272+
"""
273+
Retrieves a list of available tables.
274+
275+
This method fetches metadata about the tables that are available
276+
in the specified catalog and schema.
277+
278+
Args:
279+
session_id: The session identifier
280+
max_rows: Maximum number of rows to fetch in a single batch
281+
max_bytes: Maximum number of bytes to fetch in a single batch
282+
cursor: The cursor object that will handle the results
283+
catalog_name: Optional catalog name to filter tables
284+
schema_name: Optional schema name to filter tables
285+
table_name: Optional table pattern to filter tables by name
286+
table_types: Optional list of table types to include (e.g., "TABLE", "VIEW")
287+
288+
Returns:
289+
ExecuteResponse: An object containing the table metadata
290+
291+
Raises:
292+
ValueError: If the session ID is invalid
293+
OperationalError: If there's an error retrieving the tables
294+
"""
97295
pass
98296

99297
@abstractmethod
@@ -108,29 +306,109 @@ def get_columns(
108306
table_name:Optional[str]=None,
109307
column_name:Optional[str]=None,
110308
)->Any:
309+
"""
310+
Retrieves column metadata for tables.
311+
312+
This method fetches metadata about the columns in the specified
313+
catalog, schema, and table.
314+
315+
Args:
316+
session_id: The session identifier
317+
max_rows: Maximum number of rows to fetch in a single batch
318+
max_bytes: Maximum number of bytes to fetch in a single batch
319+
cursor: The cursor object that will handle the results
320+
catalog_name: Optional catalog name to filter columns
321+
schema_name: Optional schema name to filter columns
322+
table_name: Optional table name to filter columns
323+
column_name: Optional column pattern to filter columns by name
324+
325+
Returns:
326+
ExecuteResponse: An object containing the column metadata
327+
328+
Raises:
329+
ValueError: If the session ID is invalid
330+
OperationalError: If there's an error retrieving the columns
331+
"""
111332
pass
112333

113334
# == Utility Methods ==
114335
@abstractmethod
115336
defhandle_to_id(self,session_id:SessionId)->Any:
337+
"""
338+
Gets the raw session ID from a SessionId object.
339+
340+
This method extracts the underlying protocol-specific identifier
341+
from the SessionId abstraction.
342+
343+
Args:
344+
session_id: The session identifier
345+
346+
Returns:
347+
The raw session ID as used by the underlying protocol
348+
349+
Raises:
350+
ValueError: If the session ID is not valid for this client's backend type
351+
"""
116352
pass
117353

118354
@abstractmethod
119355
defhandle_to_hex_id(self,session_id:SessionId)->str:
356+
"""
357+
Gets a hexadecimal string representation of a session ID.
358+
359+
This method converts the session ID to a human-readable hexadecimal string
360+
that can be used for logging and debugging.
361+
362+
Args:
363+
session_id: The session identifier
364+
365+
Returns:
366+
str: A hexadecimal string representation of the session ID
367+
368+
Raises:
369+
ValueError: If the session ID is not valid for this client's backend type
370+
"""
120371
pass
121372

122373
# Properties related to specific backend features
123374
@property
124375
@abstractmethod
125376
defstaging_allowed_local_path(self)->Union[None,str,List[str]]:
377+
"""
378+
Gets the local path(s) allowed for staging data.
379+
380+
This property returns the path or paths on the local filesystem that
381+
are allowed to be used for staging data when uploading to the server.
382+
383+
Returns:
384+
Union[None, str, List[str]]: The allowed local path(s) or None if staging is not allowed
385+
"""
126386
pass
127387

128388
@property
129389
@abstractmethod
130390
defssl_options(self)->SSLOptions:
391+
"""
392+
Gets the SSL options used by this client.
393+
394+
This property returns the SSL configuration options that are used
395+
for secure communication with the server.
396+
397+
Returns:
398+
SSLOptions: The SSL configuration options
399+
"""
131400
pass
132401

133402
@property
134403
@abstractmethod
135404
defmax_download_threads(self)->int:
136-
pass
405+
"""
406+
Gets the maximum number of threads for handling cloud fetch downloads.
407+
408+
This property returns the maximum number of concurrent threads that
409+
can be used for downloading result data when using cloud fetch.
410+
411+
Returns:
412+
int: The maximum number of download threads
413+
"""
414+
pass

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp