superwise_api.entities.dataset

class DatasetApi(superwise_api.entities.base.CoreEntitiyApi):

This class provides methods to interact with the Dataset API.

Attributes:

api_client (ApiClient): An instance of the ApiClient to make requests.
_model_name (str): The name of the model.
_resource_path (str): The path of the resource.
_dataset_source_model_name (str): The name of the dataset source model.
_dataset_source_path (str): The path of the dataset source resource.

def delete(self, dataset_id: str, **kwargs):

Deletes a dataset.

Arguments:

dataset_id (str): The id of the dataset to delete.
**kwargs: Arbitrary keyword arguments.

def get_by_id( self, dataset_id: str, **kwargs) -> superwise_api.models.dataset.dataset.Dataset:

Retrieves a dataset by its id.

Arguments:

dataset_id (str): The id of the dataset to retrieve.
**kwargs: Arbitrary keyword arguments.

Returns:

Dataset: The retrieved dataset.

def create( self, name: str, description: Optional[str] = None, schema: Optional[dict] = None, **kwargs) -> superwise_api.models.dataset.dataset.Dataset:

Creates a new dataset.

Arguments:

name (str): The name of the dataset.
description (str, optional): The description of the dataset.
schema (dict, optional): The schema of the dataset.
**kwargs: Arbitrary keyword arguments.

Returns:

Dataset: The created dataset.

def get( self, name: Optional[str] = None, description: Optional[str] = None, id: Optional[str] = None, model_version_id: Optional[str] = None, created_by: Optional[str] = None, page: Optional[Annotated[int, Strict(strict=True), Interval(gt=None, ge=1, lt=None, le=None), None]] = None, size: Optional[Annotated[int, Strict(strict=True), Interval(gt=None, ge=1, lt=None, le=500), None]] = None, **kwargs) -> superwise_api.client.models.page.Page:

Retrieves datasets based on the provided filters.

Arguments:

name (Optional[str], optional): The name of the dataset to retrieve.
description (Optional[str], optional): The description of the dataset to retrieve.
id (Optional[str], optional): The id of the dataset to retrieve.
model_version_id (Optional[str], optional): The model version id of the dataset to retrieve.
created_by (Optional[str], optional): The creator of the dataset to retrieve.
page (Optional[conint(strict=True, ge=1)], optional): The page number to retrieve.
size (Optional[conint(strict=True, le=500, ge=1)], optional): The number of datasets to retrieve per page.
**kwargs: Arbitrary keyword arguments.

Returns:

Page: A page of datasets.

def update( self, dataset_id: str, *, name: Optional[str] = None, description: Optional[str] = None, schema: Optional[dict] = None, **kwargs) -> superwise_api.models.dataset.dataset.Dataset:

Updates a dataset.

Arguments:

dataset_id (str): The id of the dataset to update.
name (str, optional): The new name of the dataset.
description (str, optional): The new description of the dataset.
schema (dict, optional): The new schema of the dataset.
**kwargs: Arbitrary keyword arguments.

Returns:

Dataset: The updated dataset.

@BaseApi.raise_exception

def connect_to_source( self, dataset_id: str, source_id: str, ingest_type: superwise_api.models.dataset_source.dataset_source.IngestType, folder: str, **kwargs):

Connects a dataset to a source.

Arguments:

dataset_id (str): The id of the dataset to connect.
source_id (str): The id of the source to connect to.
ingest_type (IngestType): The ingestion type.
folder (str): The folder path to connect to inside the bucket. e.g. "folder1/folder2".
**kwargs: Arbitrary keyword arguments.

@BaseApi.raise_exception

def get_connected_sources(self, dataset_id: str, **kwargs) -> superwise_api.client.models.page.Page:

Retrieves the sources connected to a dataset.

Arguments:

dataset_id (str): The id of the dataset to retrieve the connected sources for.
**kwargs: Arbitrary keyword arguments.

Returns:

Page: A page of connected sources.

@BaseApi.raise_exception

def get_models_for_dataset(self, dataset_id: str, **kwargs) -> superwise_api.client.models.page.Page:

Retrieves all models for a dataset.

Arguments:

dataset_id (str): The id of the dataset.
**kwargs: Arbitrary keyword arguments.

Returns:

Page: A page of models.

def log_record_to_dataset( self, dataset_id: str, data: dict, images: dict[str, tuple[bytes, str]] | None = None, **kwargs):

Log a record to a dataset.

Arguments:

dataset_id: The dataset id.
data: Record data as a dict.
images: Optional image uploads keyed by schema field name. Each value is a (image_bytes, content_type) tuple, e.g. {"photo": (raw_bytes, "image/jpeg")}.

def log_batch_to_dataset(self, dataset_id: str, records: list[dict]) -> dict:

Log multiple records via POST /v1/datasets/log-batch (JSON body, x-dataset-id header).

Each item in records is the inner record dict (field names → values), e.g. for image_link fields use {"type": "image_link", "url": "https://..."} per schema.

def update_record_in_dataset( self, dataset_id: str, key_field: str, key_value: str, record: dict, **kwargs):

Update a record via POST /{dataset_id}/update (async; waits for row then publishes).

def get_media( self, dataset_id: str, image_id: str, thumbnail: bool = False, **kwargs) -> tuple[str, bytes]:

Retrieve a single image from a dataset.

Arguments:

dataset_id: The dataset that owns the image.
image_id: Image UUID to retrieve.
thumbnail: When True, return a down-scaled thumbnail instead of the full image.

Returns:

(content_type, image_bytes) tuple, e.g. ("image/jpeg", b"\xff\xd8...").

def execute_query( self, sql: str, **kwargs) -> superwise_api.models.dataset.dataset.SqlQueryResponse:

Executes a raw SELECT SQL query and returns the results.

Arguments:

sql (str): A raw SELECT SQL query to execute.
**kwargs: Arbitrary keyword arguments passed to the API client.

Returns:

RawSqlResponse: Contains a valid flag, optional error message, and query data.

def validate_query( self, sql: str, **kwargs) -> superwise_api.models.dataset.dataset.SqlQueryResponse:

Validates a raw SELECT SQL query without executing it.

Arguments:

sql (str): A raw SELECT SQL query to validate.
**kwargs: Arbitrary keyword arguments passed to the API client.

Returns:

RawSqlResponse: Contains a valid flag and optional error message. Data is always None.

def execute_nl_query( self, query: str, dataset_ids: list[str], **kwargs) -> superwise_api.models.dataset.dataset.NaturalLanguageQueryResponse:

Convert a natural language request to SQL and execute it.

Arguments:

query (str): Plain English description of the data you want.
dataset_ids (list[str]): Dataset IDs to scope the query.
**kwargs: Arbitrary keyword arguments passed to the API client.

Returns:

NaturalLanguageQueryResponse: Contains the generated SQL, a valid flag, optional error message, and query data.

def generate_nl_query( self, query: str, dataset_ids: list[str], **kwargs) -> superwise_api.models.dataset.dataset.NaturalLanguageQueryResponse:

Convert a natural language request to SQL without executing it.

Arguments:

query (str): Plain English description of the data you want.
dataset_ids (list[str]): Dataset IDs to scope the query.
**kwargs: Arbitrary keyword arguments passed to the API client.

Returns:

NaturalLanguageQueryResponse: Contains the generated SQL and a valid flag. Data is always None.

Inherited Members

superwise_api.entities.base.BaseApi: BaseApi; api_client; wrap_api_calls; raise_exception
superwise_api.entities.base.CoreEntitiyApi: search; archive; unarchive; add_tags; remove_tags; bulk_action