Util APIs

create_agg_function(udf, /, input_type=InputType.PYTHON, *, database, name=None, signature=None, imports=None, packages=None, comment=None, **kwargs)

描述：注册一个用户自定义聚合函数（UDAF）。

输入参数：

• udf (Callable) ：要注册的用户自定义聚合函数。
• input_type (InputType) ：函数的输入类型，可选值包括PYTHON、BUILTIN、PYARROW、PANDAS。
• database (str) ：函数所属的数据库名称。
• name (Optional[str]) ：函数的名称，默认为None。
• signature (Optional[Signature]) ：函数的签名定义，可选。
• imports (Optional[Union[str, Iterable[str]]]) ：函数所需的导入模块，可以是单个字符串或字符串列表。
• packages (Optional[Union[str, Iterable[str]]]) ：函数所需的依赖包，可以是单个包名或包名列表。
• comment (Optional[str]) ：函数的注释说明，可选。
• **kwargs：其他可选的关键字参数。

返回值类型：

Callable ：注册后的函数。

create_scalar_function(udf, /, input_type=InputType.PYTHON, *, database, name=None, imports=None, packages=None, comment=None, **kwargs)

描述：注册一个新的标量用户自定义函数（Scalar UDF）。

输入参数：

• udf (Callable) ：要注册的用户自定义标量函数。
• input_type (InputType) ：函数的输入类型，可选值包括PYTHON、BUILTIN、PYARROW、PANDAS。
• database (str) ：函数所属的数据库名称。
• name (Optional[str]) ：函数的名称，默认为None。
• imports (Optional[Union[str, Iterable[str]]]) ：函数所需的导入模块，可以是单个字符串或字符串列表。
• packages (Optional[Union[str, Iterable[str]]]) ：函数所需的依赖包，可以是单个包名或包名列表。
• comment (Optional[str]) ：函数的注释说明，可选。
• **kwargs：其他可选的关键字参数。

返回值类型：tuple[str, ...]。

create_table(name, /, *, schema, table_format, database=None, temp=False, external=False, overwrite=False, if_not_exists=False, partition_by=None, table_properties=None, location=None)

描述：在指定数据库中创建一个新表。

输入参数：

• name (str) - 表的名称。
• schema (ibis.Schema) ：表的定义。
• table_format (str) ：表的存储格式。
• database (Optional[str]) ：要创建表的数据库名称。如果未指定，则使用默认数据库。
• temp (bool) ：如果为True，则创建临时表。
• external (bool)：如果为True，则创建外部表。
• overwrite (bool) ：如果为True，则在表已存在时覆盖原表。
• if_not_exists (bool)：如果为True，则仅在表不存在时创建表。
• partition_by (Optional[ibis.Schema]) ：用于对表进行分区的架构。
• table_properties (Optional[dict]) ：表的其他属性。
• location (Optional[str] ：表数据存储的位置。

返回值类型: Dataset。

create_table_function(udf, /, input_type=InputType.PYTHON, *, database, name=None, signature=None, imports=None, packages=None, comment=None, **kwargs)

描述：注册一个新的用户自定义表值函数（UDTF）。

输入参数：

• udf (Callable) ：要注册的用户自定义表值函数。
• input_type (InputType) ：函数的输入类型，可选值包括PYTHON、BUILTIN。
• database (str) ：函数所属的数据库名称。
• name (Optional[str]) ：函数的名称，默认为None。
• signature (Optional[Signature]) ：函数的签名定义，可选。
• imports (Optional[Union[str, Iterable[str]]]) ：函数所需的导入模块，可以是单个字符串或字符串列表。
• packages (Optional[Union[str, Iterable[str]]]) ：函数所需的依赖包，可以是单个包名或包名列表。
• comment (Optional[str]) ：函数的注释说明，可选。
• **kwargs：其他可选的关键字参数。

返回值类型 ：

Callable ：注册后的函数。

delete_function(name, /, *, database=None, if_it_exists=False)

描述：从指定数据库中删除一个用户自定义函数。

输入参数：

• name (str) ：要删除的函数名称。
• database (Optional[str]) ：要删除函数的数据库名称。如果未指定，则使用默认数据库。
• if_exists (bool) ：如果为True，则仅在函数存在时执行删除操作，避免因函数不存在而引发错误。

返回值类型：str。

delete_table(name, /, *, database=None, if_it_exists=False)

描述：从数据库中删除指定的Dataset。

输入参数：

• name (str) ：要删除的表的名称。
• database (Optional[str]) ：要删除表的数据库名称。如果未提供，则使用默认数据库。
• if_it_exists (bool) ：如果设置为True，则仅在表存在时删除，避免因不存在而报错。

返回值类型 ：str。

describe_function(name, /, *, database=None)

描述：描述指定数据库中的函数。

输入参数：

• name (str) ：函数名称。
• database (Optional[str]) ：函数所在的数据库名称。

返回值类型：str，函数的元数据信息。

describe_table(name, /, *, database=None)

描述：描述指定数据库中的表。

输入参数：

• name (str) ：函数名称。
• database (Optional[str]) ：表所在的数据库名称。

返回值类型：str，表的元数据信息。

drop_table(name, *, database=None, force=False)

描述：从指定数据库中删除一个表。

输入参数：

• name (str) ：要删除的表的名称。
• database (Optional[str]) ：要删除表的数据库名称。如果未提供，则使用默认数据库。
• force (bool) ：如果设置为True，则即使表包含数据也会强制删除。默认为False。

返回值类型 ：None。

get_function(name, *, database=None)

描述：从指定或默认数据库中获取一个用户自定义函数。

输入参数：

• func_name (str) ：要获取的用户自定义函数的名称。
• database (Optional[str] ：要获取函数的数据库名称。如果未提供，则使用默认数据库。

返回值类型 ：Callable，可调用的函数。

list_functions(database=None)

描述：列出指定数据库或默认数据库中的所有用户自定义函数。

输入参数：

database (Optional[str]) ：要列出函数的数据库名称。如果未提供，则使用默认数据库。

返回值类型：pandas.DataFrame。

list_tables(database=None)

描述：列出指定数据库或默认数据库中的所有表。

输入参数：

database (Optional[str]) ：要列出表的数据库名称。如果为None，则使用默认数据库。

返回值类型：list[tuple]，包含表名称的元组列表。

load_dataset(name, *, database=None)

描述：从指定数据库加载数据集。

输入参数：

• name (str) ：要加载的Dataset的名称。
• database (Optional[str]) ：要加载Dataset的数据库名称。如果未提供，则使用默认数据库。

返回值类型：Dataset。

open_table(name, *, database=None)

描述：打开指定数据库中的表。

输入参数：

• name (str) ：要打开的表的名称。
• database (Optional[str]) ：包含该表的数据库名称。如果未提供，则使用默认数据库。

返回值类型 ：Table。

set_function_staging_workspace(*, obs_server, obs_bucket_name, obs_directory_base, access_key, secret_key, security_token=None)

描述：配置函数部署所需的临时工作区，包括设置必要的凭证和存储信息。

输入参数：

• obs_server (str) ：OBS服务的地址。
• obs_bucket_name (str) ：要使用的OBS桶的名称。
• obs_directory_base (str) ：OBS中用于存储工作区数据的基目录路径。
• access_key (str) ：用于身份验证的访问密钥。
• secret_key (str) ：用于身份验证的私密密钥。
• security_token (Optional[str]) ：用于身份验证的安全令牌，如果未提供则默认为None。

返回值类型 ：None。

sql(query, **kwargs)

描述：用于执行SQL查询语句，并返回查询结果。

输入参数：

• query (str) ：要执行的SQL查询语句。
• **kwargs (Any) ：可变关键字参数，用于传递查询的额外参数。

返回值类型 ：Any，返回SQL查询的结果。

explain_plan(verbose=True)

描述：生成作业执行计划。

输入参数：

verbose(bool) ：如果为True，提供查询计划的详细说明；如果为false，则仅提供简单的执行计划。

返回值类型：str。

explain_performance()

描述：执行查询并生成计划，计划中包含执行过程中详细的性能指标。

输入参数：无。

返回值类型：str，详细的执行计划。

stats()

描述：获取当前会话的所有历史作业的执行记录。

输入参数：无。

返回值类型 ：list。