MaxFrame-specific APIs - MaxCompute - Centre de documentation Alibaba Cloud

Session

new_session

Code source : new_session

new_session(
    session_id: str = None,
    default: bool = True,
    new: bool = True,
    odps_entry: Optional[ODPS] = None
)

Crée une session MaxFrame et établit la connexion avec MaxCompute.

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`session_id`	String	Non	None	Identifiant unique de la session. Si vous ne le spécifiez pas, MaxFrame en génère un automatiquement. Lorsque `new=False`, ce paramètre identifie la session existante à réutiliser.
`default`	Boolean	Non	True	Définit la session comme valeur globale par défaut. Lorsqu'il est défini sur True, les appels suivants aux fonctions `execute()` et `fetch()` utilisent cette session sans nécessiter l'argument explicite `session`.
`new`	Boolean	Non	True	Crée une nouvelle session. Définissez ce paramètre sur False pour vous connecter à une session existante identifiée par `session_id`.
`odps_entry`	ODPS	Oui	—	Objet d'entrée MaxCompute. Consultez la section Create a MaxCompute entry point.

Renvoie : L'objet session.

Exemple

import os
from maxframe import new_session
from odps import ODPS

# Initialize the MaxCompute entry object.
# Store credentials in environment variables — do not hardcode them.
o = ODPS(
    os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    project='your-default-project',
    endpoint='your-endpoint',
)

# Create the MaxFrame session.
session = new_session(odps_entry=o)

Entrées/sorties

Les fonctions suivantes permettent de lire des données depuis MaxCompute et d'y écrire des données.

Fonction	Description
`read_odps_table`	Lit une table MaxCompute dans un DataFrame
`read_odps_query`	Exécute une requête SQL et renvoie les résultats sous forme de DataFrame
`to_odps_table`	Écrit un DataFrame dans une table MaxCompute
`to_odps_model`	Enregistre un modèle XGBoost entraîné dans MaxCompute

Choix entre `read_odps_table` et `read_odps_query` : Utilisez read_odps_table pour lire une table spécifique (avec des filtres optionnels sur les partitions et les colonnes). Privilégiez read_odps_query lorsque vous avez besoin de filtrages au niveau SQL ou de jointures entre plusieurs tables.

read_odps_table

Code source : read_odps_table

read_odps_table(
    table_name: Union[str, Table],
    partitions: Union[None, str, List[str]] = None,
    columns: Optional[List[str]] = None,
    index_col: Union[None, str, List[str]] = None,
    odps_entry: ODPS = None,
    string_as_binary: bool = None,
    append_partitions: bool = False
)

Lit les données d'une table MaxCompute et les renvoie sous forme de DataFrame. Si aucune colonne d'index n'est spécifiée, un RangeIndex est généré.

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`table_name`	String/Table	Oui	—	Nom de la table MaxCompute ou objet table à partir duquel effectuer la lecture.
`partitions`	String/List	Non	None	Partition ou liste de partitions à lire. Format : `<partition_name>=<partition_value>`. Si ce paramètre n'est pas spécifié, toutes les partitions sont lues.
`columns`	List	Non	None	Colonnes à lire. Format : `<column1>, <column2>, ...`. Si ce paramètre n'est pas spécifié, toutes les colonnes hors partition sont lues.
`index_col`	String/List	Non	None	Une ou plusieurs colonnes à utiliser comme index du DataFrame.
`odps_entry`	ODPS	Non	None	Objet d'entrée MaxCompute. Consultez la section Create a MaxCompute entry point.
`string_as_binary`	Boolean	Non	None	Lit les colonnes de type chaîne au format binaire.
`append_partitions`	Boolean	Non	False	Lorsqu'il est défini sur True et que `columns` n'est pas spécifié, inclut les colonnes de clé de partition dans le résultat.

Renvoie : Un objet DataFrame.

Exemple

import maxframe.dataframe as md

df = md.read_odps_table(
    'BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users',
    index_col='user_id',
    columns=['age', 'sex']
)
print(df.execute().fetch())

# Output:
#          age sex
# user_id
# 1         24   M
# 2         53   F
# 3         23   M
# 4         24   M
# 5         33   F
# ...      ...  ..
# 939       26   F
# 940       32   M
# 941       20   M
# 942       48   F
# 943       22   M
#
# [943 rows x 2 columns]

read_odps_query

Code source : read_odps_query

read_odps_query(
    query: str,
    odps_entry: ODPS = None,
    index_col: Union[None, str, List[str]] = None,
    string_as_binary: bool = None
)

Exécute une requête SQL MaxCompute et renvoie les résultats sous forme de DataFrame. Si aucune colonne d'index n'est spécifiée, un RangeIndex est généré.

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`query`	String	Oui	—	Instruction SQL MaxCompute à exécuter.
`odps_entry`	ODPS	Non	None	Objet d'entrée MaxCompute. Consultez la section Create a MaxCompute entry point.
`index_col`	String/List	Non	None	Une ou plusieurs colonnes à utiliser comme index du DataFrame.
`string_as_binary`	Boolean	Non	None	Lit les colonnes de type chaîne au format binaire.

Renvoie : Un objet DataFrame.

Exemple

import maxframe.dataframe as md

df = md.read_odps_query(
    'SELECT user_id, age, sex FROM `BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users`'
)

to_odps_table

Code source : to_odps_table

to_odps_table(
    table: Union[Table, str],
    partition: Optional[str] = None,
    partition_col: Union[None, str, List[str]] = None,
    overwrite: bool = False,
    unknown_as_string: Optional[bool] = None,
    index: bool = True,
    index_label: Union[None, str, List[str]] = None,
    lifecycle: Optional[int] = None
)

Écrit un DataFrame dans une table MaxCompute. Si la table n'existe pas, MaxFrame la crée automatiquement.

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`table`	String/Table	Oui	—	Nom de la table cible ou objet table.
`partition`	String	Non	None	Partition cible. Exemple : `pt1=xxx, pt2=yyy`.
`partition_col`	String/List	Non	None	Colonnes du DataFrame à utiliser comme clés de partition dans la table de sortie.
`overwrite`	Boolean	Non	False	Écrase les données si la table ou la partition existe déjà.
`unknown_as_string`	Boolean	Non	False	Lorsqu'il est défini sur True, les colonnes de type objet du DataFrame sont écrites au format STRING. Une erreur peut survenir si la conversion de type échoue.
`index`	Boolean	Non	True	Écrit l'index du DataFrame en tant que colonne dans la table de sortie.
`index_label`	String/List	Non	None	Nom de colonne pour l'index. La valeur par défaut est `index` pour un index à un seul niveau, ou `level_x` (où x représente le niveau de l'index) pour un index multiniveau.
`lifecycle`	int	Non	None	Durée de vie de la table de sortie en jours (entier positif). Si la table existe déjà, cette valeur écrase le paramètre de durée de vie actuel.

Renvoie : Un objet DataFrame.

Exemple

import maxframe.dataframe as md

df = md.read_odps_query(
    'SELECT user_id, age, sex FROM `BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users`',
    index_col='user_id'
)
df.to_odps_table('output_table', lifecycle=7)

to_odps_model

to_odps_model(
    model_name: str,
    model_version: str = None,
    schema: str = None,
    project: str = None,
    description: Optional[str] = None,
    version_description: Optional[str] = None,
    create_model: bool = True,
    set_default_version: bool = False
)

Enregistre un modèle XGBoost entraîné lors d'une tâche MaxFrame en tant qu'objet modèle MaxCompute. Appelez .execute() sur le Scalar renvoyé pour déclencher l'opération d'enregistrement.

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`model_name`	String	Oui	—	Nom du modèle. Si `project` et `schema` sont spécifiés séparément, indiquez uniquement le nom du modèle. Sinon, utilisez le format `project.schema.model_name`.
`model_version`	String	Non	None	Version du modèle. Si ce paramètre n'est pas spécifié, le système génère automatiquement une version.
`schema`	String	Non	`"default"`	Schema auquel appartient le modèle.
`project`	String	Non	None	Projet auquel appartient le modèle.
`description`	String	Non	None	Description du modèle.
`version_description`	String	Non	None	Description de la version du modèle.
`create_model`	Boolean	Non	True	Crée le modèle s'il n'existe pas déjà.
`set_default_version`	Boolean	Non	False	Définit la version enregistrée comme version par défaut du modèle.

Renvoie : Un objet Scalar. Appelez .execute() pour déclencher l'opération d'enregistrement du modèle.

Exemple

from maxframe.learn.contrib.xgboost import XGBClassifier
import maxframe.dataframe as md

# Train an XGBoost model.
X_df = md.DataFrame(X, columns=cols)
clf = XGBClassifier(n_estimators=10)
clf.fit(X_df, y)

# Save the model to MaxCompute.
clf.to_odps_model(
    model_name='my_model',
    # If project and schema are not specified separately,
    # use the format: model_name='project.schema.my_model'
    model_version='version1'
).execute()

Exécution

execute

Code source : execute

execute(
    session: SessionType = None
)

Soumet une tâche de traitement des données à MaxCompute pour exécution. MaxFrame utilisant une exécution différée (lazy execution), les opérations sur un DataFrame ne sont pas calculées tant que vous n'appelez pas execute().

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`session`	Session	Non	None	Session à utiliser pour l'exécution. Si ce paramètre n'est pas spécifié, la session globale par défaut créée par `new_session` est utilisée.

Renvoie : None.

Exemple

import maxframe.dataframe as md

df = md.read_odps_query(
    'SELECT user_id, age, sex FROM BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users',
    index_col='user_id'
)
df.execute()

Récupération des résultats

fetch

Code source : fetch

fetch(
    session: SessionType = None
)

Récupère le résultat du calcul depuis MaxCompute et le renvoie sous forme de pandas DataFrame ou Series dans votre environnement local. Appelez toujours execute() avant fetch().

Paramètres

Paramètre	Type	Obligatoire	Valeur par défaut	Description
`session`	Session	Non	None	Session à utiliser pour la récupération des résultats. Si ce paramètre n'est pas spécifié, la session globale par défaut créée par `new_session` est utilisée.

Renvoie : Un pandas DataFrame ou Series.

Exemple

import maxframe.dataframe as md

df = md.read_odps_query(
    'SELECT user_id, age, sex FROM `BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users`',
    index_col='user_id'
)
result = df.execute().fetch()
print(result)

# Output:
#          age sex
# user_id
# 1         24   M
# 2         53   F
# 3         23   M
# 4         24   M
# 5         33   F
# ...      ...  ..
# 939       26   F
# 940       32   M
# 941       20   M
# 942       48   F
# 943       22   M
#
# [943 rows x 2 columns]