From c306506dc2addc82a8199ef6500cc7389c8e59f2 Mon Sep 17 00:00:00 2001 From: Nicola Coretti Date: Tue, 3 Dec 2024 16:06:18 +0100 Subject: [PATCH] Migrate documentation of ExaMetaData to doc strings --- pyexasol/meta.py | 231 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 223 insertions(+), 8 deletions(-) diff --git a/pyexasol/meta.py b/pyexasol/meta.py index ad2d7c9..dda6a4d 100644 --- a/pyexasol/meta.py +++ b/pyexasol/meta.py @@ -4,12 +4,17 @@ class ExaMetaData(object): """ - This class implements lock-free meta data requests using `/*snapshot execution*/` SQL hint described in IDEA-476 - https://www.exasol.com/support/browse/IDEA-476 + This class implements lock-free meta data requests using ``/*snapshot execution*/`` SQL hint described in `IDEA-476 `_. - If you still get locks, please make sure to update Exasol server to the latest minor version + Note: + If you still get locks, please make sure to update Exasol server to the latest minor version - This class also implements no SQL metadata commands introduced in Exasol v7.0 via .execute_meta_nosql() function + Examples: + + You may access these functions using `.meta` property of connection object. + + >>> C = pyexasol.connect(...) + ... print(C.meta.sql_columns('SELECT 1 AS id')) """ snapshot_execution_hint = '/*snapshot execution*/' @@ -20,6 +25,16 @@ def __init__(self, connection): def sql_columns(self, query, query_params=None): """ Get result set columns of SQL query without executing it + + Args: + query: + SQL query text, possibly with placholders. + query_params: + Values for placholders. + + Returns: + Columns of SQL query result without executing it. + Output format is similar to :meth:`pyexasol.ExaStatement.columns`. """ st = self.connection.cls_statement(self.connection, query, query_params, prepare=True) columns = st.columns() @@ -28,6 +43,16 @@ def sql_columns(self, query, query_params=None): return columns def schema_exists(self, schema_name): + """ + Check if schema exists. + + Args: + schema_name: + Name of the schema to check. + + Returns: + ``True`` if the schema exists, otherwise ``False``. + """ object_name = self.connection.format.default_format_ident_value(schema_name) if self.connection.protocol_version() >= constant.PROTOCOL_V2: @@ -46,6 +71,17 @@ def schema_exists(self, schema_name): return st.rowcount() > 0 def table_exists(self, table_name): + """ + Check if table exists. + + Args: + table_name: + Name of the table to check for. + If schema was not specified, ``current_schema`` is used. + + Returns: + ``True`` if the table exists, otherwise ``False``. + """ if isinstance(table_name, tuple): object_schema = self.connection.format.default_format_ident_value(table_name[0]) object_name = self.connection.format.default_format_ident_value(table_name[1]) @@ -73,6 +109,17 @@ def table_exists(self, table_name): return st.rowcount() > 0 def view_exists(self, view_name): + """ + Check if view exists. + + Args: + view_name: + Name of the table to check for. + If schema was not specified, ``current_schema`` is used. + + Returns: + ``True`` if the view exists, otherwise ``False``. + """ if isinstance(view_name, tuple): object_schema = self.connection.format.default_format_ident_value(view_name[0]) object_name = self.connection.format.default_format_ident_value(view_name[1]) @@ -100,6 +147,20 @@ def view_exists(self, view_name): return st.rowcount() > 0 def list_schemas(self, schema_name_pattern='%'): + """ + List Schemas. + + Args: + schema_name_pattern: + Schema name or LIKE-pattern to filter on. + (default: ``'%'``) + + Returns: + List of schemas from `EXA_SCHEMAS `_ system view matching LIKE-pattern. + + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_schemas @@ -112,6 +173,23 @@ def list_schemas(self, schema_name_pattern='%'): return st.fetchall() def list_tables(self, table_schema_pattern='%', table_name_pattern='%'): + """ + List Tables. + + Args: + table_schema_pattern: + Schema name or LIKE-pattern to filter on. + (default: ``'%'``) + table_name_pattern: + Table name or LIKE-pattern to filter on. + (default: ``'%'``) + + Returns: + List of tables from `EXA_ALL_TABLES `_ system view matching LIKE-pattern. + + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_all_tables @@ -126,6 +204,23 @@ def list_tables(self, table_schema_pattern='%', table_name_pattern='%'): return st.fetchall() def list_views(self, view_schema_pattern='%', view_name_pattern='%'): + """ + List Views. + + Args: + view_schema_pattern: + Schema name or LIKE-pattern to filter on. + (default: ``'%'``) + view_name_pattern: + Table name or LIKE-pattern to filter on. + (default: ``'%'``) + + Returns: + List of views from `EXA_ALL_VIEWS `_ system view matching LIKE-pattern. + + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_all_views @@ -141,6 +236,29 @@ def list_views(self, view_schema_pattern='%', view_name_pattern='%'): def list_columns(self, column_schema_pattern='%', column_table_pattern='%' , column_object_type_pattern='%', column_name_pattern='%'): + """ + List Columns. + + Args: + column_schema_pattern: + Schema name or LIKE-pattern to filter on. + (default: ``'%'``) + column_table_pattern: + Table name or LIKE-pattern to filter on. + (default: ``'%'``) + column_object_type_pattern: + Object type or LIKE-pattern to filter on. + (default: ``'%'``) + column_name_pattern: + Column name or LIKE-pattern to filter on. + (default: ``'%'``) + + Returns: + List of columns from `EXA_ALL_COLUMNS `_ system view matching LIKE-pattern. + + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_all_columns @@ -158,6 +276,29 @@ def list_columns(self, column_schema_pattern='%', column_table_pattern='%' return st.fetchall() def list_objects(self, object_name_pattern='%', object_type_pattern='%', owner_pattern='%', root_name_pattern='%'): + """ + List Objects. + + Args: + object_name_pattern: + Object name or LIKE-pattern to filter on. + (default: ``'%'``) + object_type_pattern: + Object type or LIKE-pattern to filter on. + (default: ``'%'``) + owner_pattern: + Owner name or LIKE-pattern to filter on. + (default: ``'%'``) + root_name_pattern: + Root name or LIKE-pattern to filter on.j + It normally refers to schema name. + (default: ``'%'``) + + Returns: + List of objects from `EXA_ALL_OBJECTS `_ system view matching LIKE-pattern. + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_all_objects @@ -175,6 +316,29 @@ def list_objects(self, object_name_pattern='%', object_type_pattern='%', owner_p return st.fetchall() def list_object_sizes(self, object_name_pattern='%', object_type_pattern='%', owner_pattern='%', root_name_pattern='%'): + """ + List Objects with their respective size. + + Args: + object_name_pattern: + Object name or LIKE-pattern to filter on. + (default: ``'%'``) + object_type_pattern: + Object type or LIKE-pattern to filter on. + (default: ``'%'``) + owner_pattern: + Owner name or LIKE-pattern to filter on. + (default: ``'%'``) + root_name_pattern: + Root name or LIKE-pattern to filter on.j + It normally refers to schema name. + (default: ``'%'``) + + Returns: + List of objects with sizes from `EXA_ALL_OBJECT_SIZES `_ system view matching LIKE-pattern. + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_all_object_sizes @@ -192,6 +356,26 @@ def list_object_sizes(self, object_name_pattern='%', object_type_pattern='%', ow return st.fetchall() def list_indices(self, index_schema_pattern='%', index_table_pattern='%', index_owner_pattern='%'): + """ + List indicies. + + Args: + index_schema_pattern: + Schema name or LIKE-pattern to filter on. + (default: ``'%'``) + index_table_pattern: + Table name or LIKE-pattern to filter on. + (default: ``'%'``) + index_owner_pattern: + Owner name or LIKE-pattern to filter on. + (default: ``'%'``) + + Returns: + List of indices with sizes from `EXA_ALL_INDICES `_ system view matching LIKE-pattern. + + Note: + Patterns are case-sensitive. You may escape LIKE-patterns. + """ st = self.execute_snapshot(""" SELECT * FROM sys.exa_all_indices @@ -209,7 +393,14 @@ def list_indices(self, index_schema_pattern='%', index_table_pattern='%', index_ def list_sql_keywords(self): """ Get reserved SQL keywords which cannot be used as identifiers without double-quote escaping - Never hardcode this list! It might change with next Exasol server version without warning + + Returns: + List of SQL keywords from `EXA_SQL_KEYWORDS `_ system view. + + Warning: + Never hardcode this list! It might change with next Exasol server version without warning + Note: + These keywords cannot be used as identifiers without double quotes. """ if not self.sql_keywords: if self.connection.protocol_version() >= constant.PROTOCOL_V2: @@ -231,7 +422,20 @@ def list_sql_keywords(self): def execute_snapshot(self, query, query_params=None): """ Execute query in snapshot transaction mode using SQL hint - fetch_dict=True is enforced to prevent users from relying on order of columns in system views + + Args: + query: + SQL query text, possibly with placeholders. + query_params: + Values for placeholders. + Returns: + :class:`ExaStatement` + + Warning: + Please do not try to query normal tables with this method. It will fail during creation of indices or statistics objects. + + Note: + ``fetch_dict=Tru`` is enforced to prevent users from relying on order of columns in system views """ options = { 'fetch_dict': True, @@ -242,9 +446,20 @@ def execute_snapshot(self, query, query_params=None): def execute_meta_nosql(self, meta_command, meta_params=None): """ Execute no SQL meta data command introduced in Exasol 7.0+ - This feature requires WebSocket protocol v2 or higher - List of available commands: https://github.com/exasol/websocket-api/blob/master/docs/WebsocketAPIV2.md#metadata-related-commands + Args: + meta_command: + Metadata command. + meta_params: + Parameters for metadata command. + + Returns: + :class:`ExaStatement` + + Note: + This feature requires WebSocket protocol v2 or higher + + List of available commands can be found `here `_. """ if self.connection.protocol_version() < constant.PROTOCOL_V2: raise ExaRuntimeError(self.connection, 'Protocol version 2 is required to execute nosql meta data commands')