Client¶
Low level API for interacting directly with the Gretel API
-
class
gretel_client.client.
Client
(*, host: str, api_key: str = None)¶ A single client connection to the Gretel API.
-
detect_entities
(records: Union[List[dict], dict]) → List[dict]¶ Do real-time entity detection from a small batch of records. This function operates outside the scope of a Gretel Project. It uses the Gretel API to do real-time entity detection on JSON records (dicts).
- Parameters
records – A single or small list of records.
- Returns
A list of dictionaries similar to the records received when consuming from a project stream.
-
get_project
(*, name: str = None, create: bool = False, desc: str = None, display_name: str = None) → gretel_client.projects.Project¶ Create or get a project. By default, this method will try and fetch an existing Gretel project. If the project does not exist or you are not a member, a
NotFound
exception will be thrown.Additionally, you can try and create the project by setting the
create
flag toTrue
. If this flag is set and the project already exists,Project
instance will be returned. If the project does not already exist, Gretel will attempt to create it for you. If the project name is not available then aBadRequest
will be returned.Finally, if you just need a quick project to work with, Gretel can name the project for you by omitting the
name
:client.get_project(create=True)
- Parameters
name – The unique name of the project to get or create.
create – If the project does not exist, try and create it. If no project name is provided, create a unique name based on the authenticated user.
desc – If project gets created, set the description to this value. This will only get used when a project gets newly created. If the project already exists, nothing will happen with this value.
display_name – If project gets created, set the display name to this value. This will be the primary name used when looking at the project in the Gretel Console.
- Returns
A
Project
instance.- Raises
Unauthorized or BadRequest –
-
get_sample
(sample_name: str, as_df=False, **kwargs) → Union[List[Dict], pandas.core.frame.DataFrame]¶ Returns a sample dataset by key. Use
list_samples
to get a list of available samples.- Parameters
sample_name – The name of the sample to return.
as_df – If
True
, will return the sample dataset as aDataFrame
. If the sample record contains nested fields, those fields will be flattened before converting to aDataFrame
. Defaults toFalse
.
- Returns
A list or DataFrame containing the sample dataset.
- Raises
RuntimeError if a DataFrame is requested without pandas being installed. –
-
install_packages
(verbose: bool = False, version: str = 'latest')¶ Installs the latest version of the Gretel Transformers package
- Parameters
verbose – Will print all package installation messages.
version – Eg:
1.1.0
. Determines package version to install. Specifyingwill ensure the latest version of the package is installed. ("latest") –
-
install_transformers
()¶ Deprecated: Installs the latest version of the Gretel Transformers package
Prefer
install_packages
instead.
-
list_samples
(include_details: bool = False, **kwargs) → List[Union[str, dict]]¶ Gretel provides a number of different sample datasets that can be used to populate projects. This method returns a list of available samples.
- Parameters
include_details – If
True
, the function will return additional sample details. DefultFalse
.- Returns
A list of available sample datasets.
-
search_projects
(count=200, query=None) → List[gretel_client.projects.Project]¶ Search for projects that you are a member of.
- Parameters
count – the max number of projects to return
query – an optional query string to filter projects on
- Returns
A list of
Project
instances
-
-
class
gretel_client.client.
WriteSummary
(success: bool = True, api_errors: List[dict] = <factory>, records_sent: int = 0)¶ This object is returned from write operations that use threading to batch records to the API.
Note
This object is truthy and can be evaluated as a bool.
-
api_errors
: List[dict] = None¶ A list of unique errors (as strings) returned from the API if the upload operation was not successful
-
records_sent
: int = 0¶ Tracks the number of records written to the API
-
success
: bool = True¶ Whether or not the batch upload of data was successful
-
-
gretel_client.client.
get_cloud_client
(prefix: str, api_key: str) → gretel_client.client.Client¶ Factory function that creates a
Client
instance.- Parameters
prefix – The API designator, such as “api”
api_key – Your Gretel API key
Note
If
api_key
is “prompt”, and your GRETEL_API_KEY is unset, you will be prompted to enter an api key. If “prompt_always” is set, you will always be prompted for an api key, even if a key is already set on the environment. This is useful for Jupyter Notebooks, etc.- Returns
A
Client
instance
-
gretel_client.client.
project_from_uri
(uri: str) → gretel_client.projects.Project¶ Get a Project instance from a Gretel URI string, the URI string must have the following format: gretel://[API_KEY]@HOSTNAME/PROJECT
Example:
gretel://grtu12345@api.gretel.cloud/my_project
If your API key is set as an environment variable, you may omit the API key portion of the URI:
gretel://api.gretel.cloud/my_project
Note
If
uri
is “prompt”, and your GRETEL_URI is unset, you will be prompted to enter a URI. If “prompt_always” is set, you will always be prompted for a project URI, even if a URI is already set on the environment. This is useful for Jupyter Notebooks, etc.
-
gretel_client.client.
temporary_project
(client: gretel_client.client.Client)¶ A temporary project context manager. Create a new project that can be used inside of a “with” statement for temporary purposes. The project will be deleted from Gretel Cloud when the scope is exited.
Example:
with temporary_project(client) as proj: proj.send(my_record_list) print(proj.entities)