MaxFrame-specific APIs - MaxCompute: Central de Documentação do Alibaba Cloud

Sessão

new_session

Código-fonte: new_session

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

Cria uma sessão do MaxFrame e conecta-se ao MaxCompute.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`session_id`	String	Não	None	Identificador exclusivo da sessão. Se não especificado, o MaxFrame gera um automaticamente. Quando `new=False`, identifica a sessão existente a reutilizar.
`default`	Boolean	Não	True	Defina a sessão como padrão global. Se verdadeiro, chamadas subsequentes a `execute()` e `fetch()` usam esta sessão sem exigir o argumento explícito `session`.
`new`	Boolean	Não	True	Crie uma nova sessão. Defina como False para conectar-se a uma sessão existente identificada por `session_id`.
`odps_entry`	ODPS	Sim	—	Objeto de entrada do MaxCompute. Consulte Criar um ponto de entrada do MaxCompute.

Retorno: O objeto de sessão.

Exemplo

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)

Entrada/Saída

As funções a seguir leem dados do MaxCompute e gravam dados nele.

Função	Descrição
read_odps_table	Lê uma tabela do MaxCompute em um DataFrame
read_odps_query	Execute uma consulta SQL e retorna os resultados como um DataFrame
to_odps_table	Grava um DataFrame em uma tabela do MaxCompute
to_odps_model	Salve um modelo XGBoost treinado no MaxCompute

Como escolher entre read_odps_table e read_odps_query: Use read_odps_table para ler de uma tabela específica (com filtros opcionais de partição e coluna). Prefira read_odps_query quando precisar de filtragem no nível de SQL ou junções entre várias tabelas.

read_odps_table

Código-fonte: 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
)

Lê dados de uma tabela do MaxCompute e os retorna como um DataFrame. Se nenhuma coluna de índice for especificada, um RangeIndex será gerado.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`table_name`	String/Table	Sim	—	Nome da tabela do MaxCompute ou objeto de tabela de onde os dados serão lidos.
`partitions`	String/List	Não	None	Partição ou lista de partições a ler. Formato: `<partition_name>=<partition_value>`. Se não especificado, todas as partições são lidas.
`columns`	List	Não	None	Colunas a ler. Formato: `<column1>, <column2>, ...`. Se não especificado, todas as colunas que não são de partição são lidas.
`index_col`	String/List	Não	None	Uma ou mais colunas para usar como índice do DataFrame.
`odps_entry`	ODPS	Não	None	Objeto de entrada do MaxCompute. Consulte Criar um ponto de entrada do MaxCompute.
`string_as_binary`	Boolean	Não	None	Lê colunas do tipo string em formato binário.
`append_partitions`	Boolean	Não	False	Quando verdadeiro e `columns` não estiver especificado, inclui as colunas de chave de partição no resultado.

Retorno: Um objeto DataFrame.

Exemplo

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

Código-fonte: 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
)

Execute uma consulta SQL do MaxCompute e retorna os resultados como um DataFrame. Se nenhuma coluna de índice for especificada, um RangeIndex será gerado.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`query`	String	Sim	—	Instrução SQL do MaxCompute a executar.
`odps_entry`	ODPS	Não	None	Objeto de entrada do MaxCompute. Consulte Criar um ponto de entrada do MaxCompute.
`index_col`	String/List	Não	None	Uma ou mais colunas para usar como índice do DataFrame.
`string_as_binary`	Boolean	Não	None	Lê colunas do tipo string em formato binário.

Retorno: Um objeto DataFrame.

Exemplo

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

Código-fonte: 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
)

Grava um DataFrame em uma tabela do MaxCompute. Se a tabela não existir, o MaxFrame a cria automaticamente.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`table`	String/Table	Sim	—	Nome da tabela de destino ou objeto de tabela.
`partition`	String	Não	None	Partição de destino. Exemplo: `pt1=xxx, pt2=yyy`.
`partition_col`	String/List	Não	None	Colunas do DataFrame a usar como colunas de chave de partição na tabela de saída.
`overwrite`	Boolean	Não	False	Sobrescreve os dados se a tabela ou partição já existir.
`unknown_as_string`	Boolean	Não	False	Quando verdadeiro, colunas do tipo objeto no DataFrame são gravadas como STRING. Pode ocorrer um erro se a conversão de tipo falhar.
`index`	Boolean	Não	True	Grava o índice do DataFrame como uma coluna na tabela de saída.
`index_label`	String/List	Não	None	Nome da coluna para o índice. O padrão é `index` para um índice de nível único, ou `level_x` (onde x é o nível do índice) para um índice multinível.
`lifecycle`	int	Não	None	Ciclo de vida da tabela de saída em dias (inteiro positivo). Se a tabela já existir, este valor sobrescreve a configuração atual de ciclo de vida.

Retorno: Um objeto DataFrame.

Exemplo

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
)

Salve um modelo XGBoost treinado em um job do MaxFrame como um objeto de modelo do MaxCompute. Chame .execute() no Scalar retornado para acionar a operação de salvamento.

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`model_name`	String	Sim	—	Nome do modelo. Se `project` e `schema` forem especificados separadamente, forneça apenas o nome do modelo. Caso contrário, use o formato `project.schema.model_name`.
`model_version`	String	Não	None	Versão do modelo. Se não especificada, o sistema gera uma versão automaticamente.
`schema`	String	Não	`"default"`	Schema ao qual o modelo pertence.
`project`	String	Não	None	Projeto ao qual o modelo pertence.
`description`	String	Não	None	Descrição do modelo.
`version_description`	String	Não	None	Descrição da versão do modelo.
`create_model`	Boolean	Não	True	Crie o modelo caso ele ainda não exista.
`set_default_version`	Boolean	Não	False	Defina a versão salva como a versão padrão do modelo.

Retorno: Um objeto Scalar. Chame .execute() para acionar a operação de salvamento do modelo.

Exemplo

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()

Execução

execute

Código-fonte: execute

execute(
    session: SessionType = None
)

Envia uma tarefa de processamento de dados ao MaxCompute para execução. Como o MaxFrame utiliza execução lazy, as operações em um DataFrame só são computadas quando você chama execute().

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`session`	Session	Não	None	Sessão a usar para execução. Se não especificada, a sessão padrão global criada por `new_session` será utilizada.

Retorno: None.

Exemplo

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()

Recuperação

fetch

Código-fonte: fetch

fetch(
    session: SessionType = None
)

Recupera o resultado da computação do MaxCompute e o retorna como um DataFrame ou Series do pandas no seu ambiente local. Sempre chame execute() antes de fetch().

Parâmetros

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`session`	Session	Não	None	Sessão a usar para recuperar resultados. Se não especificada, a sessão padrão global criada por `new_session` será utilizada.

Retorno: Um DataFrame ou Series do pandas.

Exemplo

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]