gravitino.client.gravitino_client.GravitinoClient

class gravitino.client.gravitino_client.GravitinoClient(uri: str, metalake_name: str, check_version: bool = True, auth_data_provider: AuthDataProvider = None, request_headers: dict | None = None, client_config: dict | None = None)

Bases: GravitinoClientBase, SupportsJobs, TagOperations

Gravitino Client for a user to interact with the Gravitino API, allowing the client to list, load, create, and alter Catalog.

It uses an underlying {@link RESTClient} to send HTTP requests and receive responses from the API.

__init__(uri: str, metalake_name: str, check_version: bool = True, auth_data_provider: AuthDataProvider = None, request_headers: dict | None = None, client_config: dict | None = None)

Constructs a new GravitinoClient with the given URI, authenticator and AuthDataProvider.

Args:

uri: The base URI for the Gravitino API. metalake_name: The specified metalake name. auth_data_provider: The provider of the data which is used for authentication. request_headers: The headers to be included in the HTTP requests. client_config: The config properties for the HTTP Client

Raises:

NoSuchMetalakeException if the metalake with specified name does not exist.

Methods

__init__(uri, metalake_name[, ...])	Constructs a new GravitinoClient with the given URI, authenticator and AuthDataProvider.
add_group(group)	Add a group to the metalake.
add_user(user)	Add a user to the metalake.
alter_catalog(name, *changes)
alter_job_template(job_template_name, *changes)	Alters a job template with the specified changes.
alter_tag(tag_name, *changes)	Alter a tag under a metalake.
cancel_job(job_id)	Cancels a job by its ID.
check_metalake_name(metalake_name)
check_version()	Check the compatibility of the client with the target server.
close()	Closes the GravitinoClient and releases any underlying resources.
create_catalog(name, catalog_type, provider, ...)
create_role(role_name[, properties, ...])	Create a new role under the metalake.
create_tag(tag_name, comment, properties)	Create a new tag under a metalake.
delete_job_template(job_template_name)	Deletes a job template by its name.
delete_role(role_name)	Delete a role from the metalake.
delete_tag(tag_name)	Delete a tag under a metalake.
disable_catalog(name)
drop_catalog(name[, force])
enable_catalog(name)
get_client_version()	Retrieves the version of the Gravitino Python Client.
get_group(group)	Get a group by name from the metalake.
get_job(job_id)	Retrieves a job by its ID.
get_job_template(job_template_name)	Retrieves a job template by its name.
get_metalake()	Get the current metalake object
get_owner(metadata_object)	Get the owner of a metadata object.
get_role(role_name)	Get a role by name from the metalake.
get_server_version()	Retrieves the version of the Gravitino API.
get_tag(tag_name)	Get a tag by its name under a metalake.
get_user(user)	Get a user by name from the metalake.
grant_privileges_to_role(role_name, ...)	Grant privileges to a role on a securable object.
grant_roles_to_group(role_names, group_name)	Grant roles to a group.
grant_roles_to_user(role_names, user_name)	Grant roles to a user.
list_catalogs()
list_catalogs_info()
list_group_names()	List all group names under the metalake.
list_groups()	List all groups with details under the metalake.
list_job_templates()	Lists all job templates in the current metalake.
list_jobs([job_template_name])	Lists all the jobs in the current metalake.
list_role_names()	List all role names under the metalake.
list_tags()	List all the tag names under a metalake.
list_tags_info()	List tags information under a metalake.
list_user_names()	List all user names under the metalake.
list_users()	List all users with details under the metalake.
load_catalog(name)
load_metalake(name)	Loads a specific Metalake from the Gravitino API.
register_job_template(job_template)	Register a job template with the specified job template to Gravitino.
remove_group(group)	Remove a group from the metalake.
remove_user(user)	Remove a user from the metalake.
revoke_privileges_from_role(role_name, ...)	Revoke privileges from a role on a securable object.
revoke_roles_from_group(role_names, group_name)	Revoke roles from a group.
revoke_roles_from_user(role_names, user_name)	Revoke roles from a user.
run_job(job_template_name, job_conf)	Runs a job using the specified job template and configuration.
set_owner(metadata_object, owner_name, ...)	Set the owner of a metadata object.

Attributes

API_METALAKES_IDENTIFIER_PATH	The REST API path prefix for load a specific metalake
API_METALAKES_LIST_PATH	The REST API path for listing metalakes
CLIENT_VERSION_HEADER
VERSION_CHECK_DISABLED_ENV

API_METALAKES_IDENTIFIER_PATH = 'api/metalakes/'

The REST API path prefix for load a specific metalake

API_METALAKES_LIST_PATH = 'api/metalakes'

The REST API path for listing metalakes

add_group(group: str) → Group

Add a group to the metalake.

Args:

group: The name of the group.

Returns:

The added Group object.

Raises:

GroupAlreadyExistsException: If a group with the same name already exists. NoSuchMetalakeException: If the metalake does not exist.

add_user(user: str) → User

Add a user to the metalake.

Args:

user: The name of the user.

Returns:

The added User object.

Raises:

UserAlreadyExistsException: If a user with the same name already exists. NoSuchMetalakeException: If the metalake does not exist.

alter_job_template(job_template_name: str, *changes: JobTemplateChange) → JobTemplate

Alters a job template with the specified changes.

Args:

job_template_name: The name of the job template to alter. changes: The changes to apply to the job template.

Returns:

The altered JobTemplate object.

Raises:

NoSuchJobTemplateException: If no job template with the specified name exists. IllegalArgumentException: If any of the changes cannot be applied.

alter_tag(tag_name, *changes) → Tag

Alter a tag under a metalake.

Args:

tag_name (str): The name of the tag. changes (TagChange): The changes to apply to the tag.

Returns:

Tag: The altered tag.

Raises:

NoSuchTagException: If the tag does not exist. NoSuchMetalakeException: If the metalake does not exist. IllegalArgumentException: If the changes cannot be applied to the tag. TagAlreadyExistsException: If a tag with the new name already exists.

cancel_job(job_id: str) → JobHandle

Cancels a job by its ID.

Args:

job_id: The ID of the job to cancel.

Returns:

The JobHandle object representing the cancelled job.

Raises:

NoSuchJobException: If no job with the specified ID exists.

check_version()

Check the compatibility of the client with the target server.

Raises:

GravitinoRuntimeException If the client version is greater than the server version.

close()

Closes the GravitinoClient and releases any underlying resources.

create_role(role_name: str, properties: Dict[str, str] | None = None, securable_objects: List[SecurableObject] | None = None) → Role

Create a new role under the metalake.

Args:

role_name: The name of the role. properties: The properties of the role. securable_objects: The securable objects of the role.

Returns:

The created Role object.

Raises:

RoleAlreadyExistsException: If a role with the same name already exists. NoSuchMetalakeException: If the metalake does not exist.

create_tag(tag_name, comment, properties) → Tag

Create a new tag under a metalake.

Raises:

NoSuchMetalakeException: If the metalake does not exist. TagAlreadyExistsException: If the tag already exists.

Args:

tag_name (str): The name of the tag. comment (str): The comment of the tag. properties (dict[str, str]): The properties of the tag.

Returns:

Tag: The tag information.

delete_job_template(job_template_name: str) → bool

Deletes a job template by its name. This will remove the job template from Gravitino, and it will no longer be available for execution. Only when all the jobs associated with this job template are completed, failed or cancelled, the job template can be deleted successfully, otherwise it will throw InUseException. Returns false if the job template to be deleted does not exist.

The deletion of a job template will also delete all the jobs associated with this template.

Args:

job_template_name: The name of the job template to delete.

Returns:

bool: True if the job template was deleted successfully, False if the job template does not exist.

Raises:

InUseException: If there are still queued or started jobs associated with this job template.

delete_role(role_name: str) → bool

Delete a role from the metalake.

Args:

role_name: The name of the role.

Returns:

True if the role was deleted, False otherwise.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

delete_tag(tag_name) → bool

Delete a tag under a metalake.

Args:

tag_name (str): The name of the tag.

Returns:

bool: True if the tag was deleted, False otherwise.

Raises:

NoSuchTagException: If the tag does not exist. NoSuchMetalakeException: If the metalake does not exist.

get_client_version() → GravitinoVersion

Retrieves the version of the Gravitino Python Client.

Returns:

A GravitinoVersion instance representing the version of the Gravitino Python Client.

get_group(group: str) → Group

Get a group by name from the metalake.

Args:

group: The name of the group.

Returns:

The Group object.

Raises:

NoSuchGroupException: If the group does not exist. NoSuchMetalakeException: If the metalake does not exist.

get_job(job_id: str) → JobHandle

Retrieves a job by its ID.

Args:

job_id: The ID of the job to retrieve.

Returns:

The JobHandle object corresponding to the specified job ID.

Raises:

NoSuchJobException: If no job with the specified ID exists.

get_job_template(job_template_name: str) → JobTemplate

Retrieves a job template by its name.

Args:

job_template_name: The name of the job template to retrieve.

Returns:

The JobTemplate object corresponding to the specified name.

Raises:

NoSuchJobTemplateException: If no job template with the specified name exists.

get_metalake() → GravitinoMetalake

Get the current metalake object

Raises:

NoSuchMetalakeException if the metalake with specified name does not exist.

Returns:

the GravitinoMetalake object

get_owner(metadata_object: MetadataObject) → Owner | None

Get the owner of a metadata object.

Args:

metadata_object: The metadata object to get the owner for.

Returns:

Optional[Owner]: The owner of the metadata object, or None if no owner is set.

Raises:

NoSuchMetadataObjectException: If the metadata object does not exist. NotFoundException: If a related resource is not found. MetalakeNotInUseException: If the metalake is not in use.

get_role(role_name: str) → Role

Get a role by name from the metalake.

Args:

role_name: The name of the role.

Returns:

The Role object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchMetalakeException: If the metalake does not exist.

get_server_version() → GravitinoVersion

Retrieves the version of the Gravitino API.

Returns:

A GravitinoVersion instance representing the version of the Gravitino API.

get_tag(tag_name) → Tag

Get a tag by its name under a metalake.

Args:

tag_name (str): The name of the tag.

Returns:

Tag: The tag information.

Raises:

NoSuchTagException: If the tag does not exist.

get_user(user: str) → User

Get a user by name from the metalake.

Args:

user: The name of the user.

Returns:

The User object.

Raises:

NoSuchUserException: If the user does not exist. NoSuchMetalakeException: If the metalake does not exist.

grant_privileges_to_role(role_name: str, securable_object: SecurableObject, privileges: List[Privilege]) → Role

Grant privileges to a role on a securable object.

Args:

role_name: The name of the role. securable_object: The securable object. privileges: The privileges to grant.

Returns:

The updated Role object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchMetalakeException: If the metalake does not exist. NoSuchMetadataObjectException: If the securable object does not exist. IllegalPrivilegeException: If a privilege is invalid.

grant_roles_to_group(role_names: List[str], group_name: str) → Group

Grant roles to a group.

Args:

role_names: The names of the roles to grant. group_name: The name of the group.

Returns:

The updated Group object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchGroupException: If the group does not exist. NoSuchMetalakeException: If the metalake does not exist.

grant_roles_to_user(role_names: List[str], user_name: str) → User

Grant roles to a user.

Args:

role_names: The names of the roles to grant. user_name: The name of the user.

Returns:

The updated User object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchUserException: If the user does not exist. NoSuchMetalakeException: If the metalake does not exist.

list_group_names() → list[str]

List all group names under the metalake.

Returns:

A list of group name strings.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

list_groups() → list[gravitino.api.authorization.group.Group]

List all groups with details under the metalake.

Returns:

A list of Group objects.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

list_job_templates() → List[JobTemplate]

Lists all job templates in the current metalake.

Returns:

A list of JobTemplate objects representing the job templates in the metalake.

list_jobs(job_template_name: str = None) → List[JobHandle]

Lists all the jobs in the current metalake.

Args:

job_template_name: Optional; if provided, filters the jobs by the specified job template name.

Returns:

A list of JobHandle objects representing the jobs in the metalake.

list_role_names() → list[str]

List all role names under the metalake.

Returns:

A list of role name strings.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

list_tags() → list[str]

List all the tag names under a metalake.

Returns:

list[str]: The list of tag names.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

list_tags_info() → list[gravitino.api.tag.tag.Tag]

List tags information under a metalake.

Returns:

list[Tag]: The list of tag information.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

list_user_names() → list[str]

List all user names under the metalake.

Returns:

A list of user name strings.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

list_users() → list[gravitino.api.authorization.user.User]

List all users with details under the metalake.

Returns:

A list of User objects.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

load_metalake(name: str) → GravitinoMetalake

Loads a specific Metalake from the Gravitino API.

Args:

name: The name of the Metalake to be loaded.

Returns:

A GravitinoMetalake instance representing the loaded Metalake.

Raises:

NoSuchMetalakeException If the specified Metalake does not exist.

register_job_template(job_template) → None

Register a job template with the specified job template to Gravitino. The registered job template will be maintained in Gravitino, allowing it to be executed later.

Args:

job_template: The job template to register.

Raises:

JobTemplateAlreadyExists: If a job template with the same name already exists.

remove_group(group: str) → bool

Remove a group from the metalake.

Args:

group: The name of the group.

Returns:

True if the group was removed, False if the group did not exist.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

remove_user(user: str) → bool

Remove a user from the metalake.

Args:

user: The name of the user.

Returns:

True if the user was removed, False if the user did not exist.

Raises:

NoSuchMetalakeException: If the metalake does not exist.

revoke_privileges_from_role(role_name: str, securable_object: SecurableObject, privileges: List[Privilege]) → Role

Revoke privileges from a role on a securable object.

Args:

role_name: The name of the role. securable_object: The securable object. privileges: The privileges to revoke.

Returns:

The updated Role object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchMetalakeException: If the metalake does not exist. NoSuchMetadataObjectException: If the securable object does not exist. IllegalPrivilegeException: If a privilege is invalid.

revoke_roles_from_group(role_names: List[str], group_name: str) → Group

Revoke roles from a group.

Args:

role_names: The names of the roles to revoke. group_name: The name of the group.

Returns:

The updated Group object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchGroupException: If the group does not exist. NoSuchMetalakeException: If the metalake does not exist.

revoke_roles_from_user(role_names: List[str], user_name: str) → User

Revoke roles from a user.

Args:

role_names: The names of the roles to revoke. user_name: The name of the user.

Returns:

The updated User object.

Raises:

NoSuchRoleException: If the role does not exist. NoSuchUserException: If the user does not exist. NoSuchMetalakeException: If the metalake does not exist.

run_job(job_template_name: str, job_conf: Dict[str, str]) → JobHandle

Runs a job using the specified job template and configuration.

Args:

job_template_name: The name of the job template to use for running the job. job_conf: A dictionary containing the configuration for the job.

Returns:

A JobHandle object representing the started job.

Raises:

NoSuchJobTemplateException: If no job template with the specified name exists.

set_owner(metadata_object: MetadataObject, owner_name: str, owner_type: Type) → None

Set the owner of a metadata object.

Args:

metadata_object: The metadata object to set the owner for. owner_name: The name of the owner. owner_type: The type of the owner (USER or GROUP).

Raises:

NoSuchMetadataObjectException: If the metadata object does not exist. NotFoundException: If a related resource is not found. MetalakeNotInUseException: If the metalake is not in use. UnsupportedOperationException: If the operation is not supported.