`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)

Bases: thanosql._service.ThanoSQLService

Service layer for file methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

list(path: str | os.PathLike) → dict

Lists all files and directories under the specified path.

Parameters:

path (str or path_like) – The path that contains the files and directories to be listed. It should begin with ‘drive/’. Regex pattern is recommended.

Returns:

A dictionary containing the list of files and folders under the input path in the format of:

{
    "data": {
        "matched_pathnames": [list of matched pathnames],
    }
}

Return type:

dict

Raises:

ThanoSQLValueError – If path is not within the ‘drive’ directory.

Uploads a file to the workspace.

Parameters:

path (str or path_like) – The path to the local file to be uploaded to the workspace.
db_commit (bool, optional) – Whether to save the uploaded file path to a table or not.
table (str, optional) – The name of the table to save the uploaded file path in. Only relevant if db_commit is set to True.
column (str, optional) – The column name in the table where the uploaded file path will be saved in. Only relevant if db_commit is set to True.
schema (str, optional) – The schema where the table to save the uploaded file path in resides. Only relevant if db_commit is set to True and defaults to “public”.
dir (str, optional) – Path to directory under drive/ to store the uploaded file in. If the directory does not exist, it will be created by the API.

Returns:

Dictionary containing values of “file_path”, “table_name”, “column_name”, and “schema”. “file_path” will always be returned, while the rest are only returned if db_commit is set to True. The result is in the format of:

{
    "data": {
        "file_path": file_path,
        "table_name": table_name | null,
        "column_name": column_name | null,
        "schema": schema | null
    }
}

Return type:

dict

Raises:

ThanoSQLValueError –

If dir is not within the ‘drive’ directory.
If the path cannot be saved to table due to integrity or data error.

Deletes the specified file from the workspace.

Parameters:

path (str or path_like) – The path to the file to be removed from the workspace.
db_commit (bool, optional) – Whether to remove the file path from a table or not.
table (str, optional) – The name of the table where the file path to be removed is in. Only relevant if db_commit is set to True.
column (str, optional) – The column name in the table where the file path to be removed is in. Only relevant if db_commit is set to True.
schema (str, optional) – The schema where the table to remove the file path from resides. Only relevant if db_commit is set to True and defaults to “public”.

Returns:

A dictionary containing a success message in the format of:

{
    "message": "string"
}

Return type:

dict

Raises:

ThanoSQLValueError – If path is not within the ‘drive’ directory.

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

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.
query_type (str, default "thanosql") – The type of the query to be executed. Can only be one of “thanosql” or “psql”.
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.
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 a value other than “thanosql” or “psql” is provided as query_type.
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.

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

Bases: thanosql._service.ThanoSQLService

Service layer for schema methods.

client

The ThanoSQL client used to make requests to the engine.

Type:: ThanoSQL

list() → dict

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

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)

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]

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

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

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) → Table

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”.

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.

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

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)

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]

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

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

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`