Skip to content

Commit

Permalink
Migrate documentation of ExaMetaData to doc strings
Browse files Browse the repository at this point in the history
  • Loading branch information
@Nicoretti
Nicoretti committed Dec 3, 2024
1 parent ba4b057 commit c306506
Showing 1 changed file with 223 additions and 8 deletions.
231 changes: 223 additions & 8 deletions pyexasol/meta.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://www.exasol.com/support/browse/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*/'

Expand All @@ -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()
Expand All @@ -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:
Expand All @@ -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])
Expand Down Expand Up @@ -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])
Expand Down Expand Up @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_schemas.htm>`_ system view matching LIKE-pattern.
Note:
Patterns are case-sensitive. You may escape LIKE-patterns.
"""
st = self.execute_snapshot("""
SELECT *
FROM sys.exa_schemas
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_tables.htm>`_ 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
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_views.htm>`_ 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
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_columns.htm>`_ 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
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_objects.htm>`_ 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
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_object_sizes.htm>`_ 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
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_all_indices.htm>`_ 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
Expand All @@ -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 <https://docs.exasol.com/db/latest/sql_references/system_tables/metadata/exa_sql_keywords.htm>`_ 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:
Expand All @@ -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,
Expand All @@ -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 <https://github.com/exasol/websocket-api/blob/master/docs/WebsocketAPIV2.md#metadata-related-commands>`_.
"""
if self.connection.protocol_version() < constant.PROTOCOL_V2:
raise ExaRuntimeError(self.connection, 'Protocol version 2 is required to execute nosql meta data commands')
Expand Down

0 comments on commit c306506

Please sign in to comment.