`thanosql.resources`

Package Contents

Classes

`FileService`	Service layer for file methods.
`QueryService`	Service layer for query methods.
`SchemaService`	Service layer for schema methods.
`TableService`	Service layer for table methods.
`ViewService`	Service layer for view methods.

class thanosql.resources.FileService(client: thanosql._client.ThanoSQL)[source]

Bases: thanosql._service.ThanoSQLService

Service layer for file methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

get(path: str | os.PathLike | None = None, option: str | None = None) → Content | None[source]

Details the information of a file or directory in the specified path.

Parameters:

path (str or path_like) – The path to the file/directory relative to the user data root (default value is “/”, the user data root directory itself)
option (controls the behavior of the API) –
- default (None): retrieves file/directory information
- download: downloads a file (directory download is not possible)

Returns:

Depending on option:

default (None): Returns a Content Pydantic object containing information on the target path
download: Downloads the requested file and returns nothing

Return type:

Content | None

Raises:

ThanoSQLValueError – If user attempts to download a directory (when option=”download”)

create(path: str | os.PathLike | None = None, file: str | os.PathLike | None = None) → Content[source]

Uploads a file to the workspace or creates an empty folder.

Parameters:

path (str or path_like) – The destination path of the upload/folder creation relative to the user data root. Should point to a (would-be) directory (default value is “/”, the user data root directory itself)
file (str or PathLike, optional) – The file to be uploaded. If left empty, creates an empty folder in the given path.

Return type:

A Content Pydantic object containing information on the created file/folder.

Raises:

ThanoSQLValueError – If path does not point to a (would-be) directory

delete(path: str | os.PathLike) → None[source]

Deletes the specified file or directory permanently from the workspace.

Parameters:: path (str or path_like) – The path to the file or directory to be removed from the workspace. Relative to the user data root, no default value.
Return type:: No content

class thanosql.resources.QueryService(client: thanosql._client.ThanoSQL)[source]

Bases: thanosql._service.ThanoSQLService

Service layer for query methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

log

The query log service layer to access methods involving query logs.

Type:: QueryLogService

template

The query template service layer to access methods involving query templates.

Type:: QueryTemplateService

Executes a query string.

There are three ways of requesting a query:

Using a complete query directly in query, leaving template_id, template_name, and parameters empty.
Using a template query in query and completing it with parameters, leaving template_id and template_name empty.
Recalling a template query from the database using template_id or template_name (but not both) and completing it with parameters, leaving query empty.

One, and only one, of these ways must be chosen. That is, exactly one of query, template_id, or template_name must be specified. If none or more than one way is selected, an error will occur.

Parameters:

query (str, optional) – The query string or template to be executed.
template_id (int, optional) – The ID number of the query template to be used. Only relevant when a query template from the database is needed, and query and template_name are not used simultaneously.
template_name (str, optional) – The name of the query template to be used. Only relevant when a query template from the database is needed, and query and template_id are not used simultaneously.
parameters (dict, optional) – A dictionary of parameter names and values to fill in the template. Only relevant when a query template, either from query or the database, is used.
schema (str, optional) – The schema of the table to save the query results in. If not specified and table_name is also empty, it defaults to “qm”. If table_name is specified, it defaults to “public”.
table_name (str, optional) – The name of the table to save the query results in. If not specified while the query produces a result, an automatic table name will be given.
overwrite (bool, optional) – Whether to overwrite the table if a table with the same table_name and schema already exists. If not specified, the value is False.
keep_temp_table (bool, optional) – Whether to save temporary tables produced by query execution to the “qm” schema or not. If not specified, the value is True.
max_results (int, optional) – The maximum number of records to be returned by the response QueryLog. If not specified, it defaults to 100.

Returns:

A query log object containing details about the results of the executed query.

Return type:

QueryLog

Raises:

ThanoSQLValueError –

If invalid input combination is provided; that is:
- query, template_id, and template_name are all empty, or
- more than one of query, template_id, and template_name are non-empty
If max_results is not between 0 and 100 (inclusive).
If query and parameters are used but the template has invalid format.
If rendering query template by substituting in parameters fails, either by direct query template or templates from the database.

Executes a query string with a value placeholder.

Unlike execute, query templates cannot be used, as this might be confusing when combined with value placeholders. Following psycopg, only a single main placeholder is allowed. If multiple placeholders are required, users should use templates. Unlike psycopg, we will use jinja formatting for consistency with query template purposes.

Parameters:

query (str) – The query string with a “{{ values }}” placeholder to be executed.
values (list of tuples) – List of values to be inserted to the placeholder(s).

template (str, optional) –

How values should be formatted inside {{ values }}. If it is left empty, values will just be listed inside brackets separated by commas. In this case, values should be a list of tuples. For example, we have the following values:

[(1, "gangnam", "seoul"), (2, "haeundae", "busan")]

and we leave template empty. The original query looks like:

VALUES
    {{ values }}

The rendered query will look like:

VALUES
    (1, 'gangnam', 'seoul'),
    (2, 'haeundae', 'busan')

Meanwhile, if we have the following named values:

[
    {"id": 1, "name": "gangnam", "city": "seoul"},
    {"id": 2, "name": "haeundae", "city": "busan"},
]

and we have the following template:

({{ id }}, CONCAT(INITCAP({{ name }}), '-gu'), INITCAP({{ city }}))

the rendered query will be:

VALUES
    (1, CONCAT(INITCAP('gangnam', '-gu')), INITCAP('seoul')),
    (2, CONCAT(INITCAP('haeundae', '-gu')), INITCAP('busan'))

page_size (int, default 100) – The maximum number of rows (set of values) to be sent in one statement. If not specified, it defaults to 100.
schema (str, optional) – The schema of the table to save the query results in. If not specified and table_name is also empty, it defaults to “qm”. If table_name is specified, it defaults to “public”.
table_name (str, optional) – The name of the table to save the query results in. If not specified while the query produces a result, an automatic table name will be given.
overwrite (bool, optional) – Whether to overwrite the table if a table with the same table_name and schema already exists. If not specified, the value is False.
keep_temp_table (bool, optional) – Whether to save temporary tables produced by query execution to the “qm” schema or not. If not specified, the value is True.
max_results (int, default 100) – The maximum number of records to be returned by the response QueryLog. If not specified, it defaults to 100.

Returns:

A query log object containing details about the results of the executed query.

Return type:

QueryLog

Raises:

ThanoSQLValueError –

If values is empty.
If page_size is less than 1.
If max_results is not between 0 and 100 (inclusive).
If the formats of template and values don’t match.

class thanosql.resources.SchemaService(client: thanosql._client.ThanoSQL)[source]

Bases: thanosql._service.ThanoSQLService

Service layer for schema methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

list() → dict[source]

Lists schemas stored in the workspace.

Does not have any parameters.

Returns:

A dictionary containing the names of stored schemas in the format of:

{
    "schemas": [
        {
            "name": "string"
        }
    ]
}

Return type:

dict

create(name: str) → dict[source]

Creates a new schema in the workspace.

Parameters:

name (str) – The name of the schema to be created.

Returns:

A dictionary containing the name of the created schema and a success message in the format of:

{
    "schema": "string",
    "message": "string"
}

Return type:

dict

class thanosql.resources.TableService(client: thanosql._client.ThanoSQL)[source]

Bases: thanosql._service.ThanoSQLService

Service layer for table methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

template

The table template service layer to access methods involving table templates.

Type:: TableTemplateService

list(schema: str | None = None, verbose: bool | None = None, offset: int | None = None, limit: int | None = None) → List[Table][source]

Lists tables stored in the workspace.

Parameters:

schema (str, optional) – The schema where the listed tables should reside in. If not set, all tables from all schemas will be included.
verbose (bool, optional) – Whether to include the table columns and constraints in the results. By default, or if set to False, only retrieves the names and schemas of stored tables.
offset (int, optional) – When set to n, skips the first n results and excludes them from the output list. Otherwise, starts the list from the first result stored. Must be greater than 0.
limit (int, optional) – When set to n, limits the number of results listed to n. Otherwise, lists up to 100 results per call. Must range between 0 to 100.

Returns:

A list of Table objects.

Return type:

List[Table]

Raises:

ThanoSQLValueError – If offset is less than 0 or if limit is not between 0 to 100 (inclusive).

get(name: str, schema: str | None = None) → Table[source]

Shows the details of the specified table.

Parameters:

name (str) – The name of the table to be retrieved.
schema (str, optional) – The schema where the table to be retrieved is in. If not specified, this method will look for the table in “public”.

Returns:

A Table object.

Return type:

Table

update(name: str, schema: str | None = None, table: BaseTable | None = None) → Table[source]

Updates the specified table.

Parameters:

name (str) – The name of the table to be updated.
schema (str, optional) – The schema where the table to be updated is in. If not specified, this method will look for the table in “public”.
table (BaseTable, optional) –
BaseTable object containing changed details of the table to be updated. Any attribute of BaseTable can be modified, and if left unset, the current value will be maintained after update. The attributes are as follows:
- name: new name to rename the table to
- schema: new schema to move the table to
- columns: new columns of the updated table. All new columns must be in this object, including columns that already exist in the original table. If this attribute is set but some original columns are not included, they will be removed from the table.
- constraints: new constraints of the updated table. All new constraints must be in this object, including constraints that already exist in the original table. If this attribute is set but some original constraints are not included, they will be removed from the table.

Returns:

Table object of the new table after update.

Return type:

Table

Raises:

ThanoSQLValueError – If the table object contains invalid formatting.

create(name: str, table: TableObject, schema: str | None = None, if_not_exists: bool = False) → Table[source]

Creates a new table.

Parameters:

name (str) – The name of the table to be created.
table (TableObject) – TableObject containing the columns and constraints of the table to be created. In order to create an empty table, pass in an empty object (TableObject()).
schema (str, optional) – The schema to save the created table in. If not specified, the table will be saved to “public”.
if_not_exists (bool, default False) – Whether to throw an error if a table of the same name already exists. When set to False (default), an error will be shown. When True, the table will only be created if it does not exist already. Otherwise, do nothing.

Returns:

Table object of the created table.

Return type:

Table

Raises:

ThanoSQLValueError – If the table object contains invalid formatting.

Uploads the contents of a CSV or Excel-like file or Pandas DataFrame into the specified table.

Either a CSV or Excel-like (.xls, .xlsx, .xlsm, .xlsb, .odf, .ods, .odt) file or DataFrame must be specified. However, both should not be used at the same time.

Note: If you are working with a Strict Open XML Spreadsheet (.xlsx) file, change it to Excel Workbook (.xlsx), save it, and try using it again.

Parameters:

name (str) – The name of the table created from the file or DataFrame.
file (str or PathLike, optional) – CSV or Excel-like file containing tabulated data to be uploaded to the specified table.
df (DataFrame, optional) – Pandas DataFrame containing data to be uploaded to the specified table.
schema (str, optional) – The schema to save the created table in. If not specified, the table will be saved to “public”.
table (TableObject, optional) – TableObject containing the columns and constraints of the table to be created. If specified, the created table will follow the object format and no type inference is conducted. Otherwise, type inference will be performed and the table will be created to match the columns from source.
if_exists (str, default "fail") –
What to do if table of the same name already exists. There are only three available values:
- fail: fails (throws an error) if the same table exists
- append: appends records into an existing table (columns must match in order to not make an error)
- replace: deletes existing table and creates a new one with the given name

Returns:

Table object of the uploaded table.

Return type:

Table

Raises:

ThanoSQLValueError –

If if_exists is not one of “fail”, “append”, or “replace”.
If neither file nor df is used, or if both are used at the same time.
If file is used but it is neither CSV nor Excel-like.
If the file or df contains badly-formatted contents.
If a table body is specified but does not match the contents of the file or df.
If if_exists is set to “append” but the new contents does not match the format of the existing table.

delete(name: str, schema: str | None = None) → dict[source]

Deletes the specified table.

Parameters:

name (str) – The name of the table to be deleted.
schema (str, optional) – The schema where the table to be deleted is in. If not specified, this method will look for the table in “public”.

Returns:

A dictionary containing a success message, table name, and schema in the format of:

{
    "message": "string",
    "table_name": "string",
    "schema": "string"
}

Return type:

dict

class thanosql.resources.ViewService(client: thanosql._client.ThanoSQL)[source]

Bases: thanosql._service.ThanoSQLService

Service layer for view methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

list(schema: str | None = None, verbose: bool | None = None, offset: int | None = None, limit: int | None = None) → List[View][source]

Lists views stored in the workspace.

Parameters:

schema (str, optional) – When specified, lists views from a specific schema only. Otherwise, lists views from all available schemas.
verbose (bool, optional) – When not set or set to False (default behavior), only lists view names and the schema they belong to. When set to True, includes column descriptions and view definition in the output on top of the basic (name and schema) information.
offset (int, optional) – When set to n, skips the first n views and excludes them from the output list. Otherwise, starts the list from the first view stored. Must be greater than 0.
limit (int, optional) – When set to n, limits the number of views listed to n. Otherwise, lists up to 100 views per call. Must range between 0 to 100.

Returns:

A list of View objects.

Return type:

List[View]

Raises:

ThanoSQLValueError – If offset is less than 0 or if limit is not between 0 to 100 (inclusive).

get(name: str, schema: str | None = None) → View[source]

Shows the details of the specified view.

Parameters:

name (str) – The name of the view to be retrieved.
schema (str, optional) – The schema the target view is stored in. When not specified, defaults to “public”.

Returns:

A View object.

Return type:

View

delete(name: str, schema: str | None = None) → dict[source]

Deletes the specified view.

Parameters:

name (str) – The name of the view to be deleted.
schema (str, optional) – The schema the target view is stored in. When not specified, defaults to “public”.

Returns:

A dictionary containing a success message and the name of the deleted view in the format of:

{
    "message": "string",
    "view_name": "string"
}

Return type:

dict

thanosql.resources

Package Contents

Classes

`thanosql.resources`