Todos os produtos
Search

Este produto

    MaxCompute:Primeiros passos

    Central de documentação

    MaxCompute:Primeiros passos

    Última atualização: Sep 22, 2026

    O MaxFrame é uma API de DataFrame compatível com o Pandas para o MaxCompute. Ele permite executar operações de dados no estilo Pandas em conjuntos de dados de grande escala, sem limitações de memória local ou de recursos de computação. Use o MaxFrame quando seu conjunto de dados exceder a memória de uma única máquina ou quando seus fluxos de trabalho do Pandas forem muito lentos para serem executados localmente.

    Para migrar do Pandas, altere apenas uma instrução de importação — o MaxFrame gerencia o restante ao distribuir a computação pelo backend do MaxCompute:

    # Before (pandas)
import pandas as pd

# After (MaxFrame)
import maxframe.dataframe as md
    O MaxFrame usa avaliação preguiçosa. As operações constroem um grafo de computação, mas não são executadas até que você chame o método .execute() . Encadeie múltiplas transformações livremente e, em seguida, chame o .execute() uma única vez para iniciar a computação.

    Pré-requisitos

    Antes de começar, certifique-se de ter:

    • Um projeto do MaxCompute com as permissões necessárias

    • O access key ID e o secret access key do Alibaba Cloud (definidos como variáveis de ambiente)

    • O MaxFrame instalado no seu ambiente Python

    Conjunto de dados de exemplo

    Este guia usa a tabela maxframe_ml_100k_users do conjunto de dados público do MaxCompute. A tabela está disponível em BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users — sem necessidade de importação.

    Inicializar uma sessão

    Antes de executar qualquer job do MaxFrame, inicialize uma sessão no ponto de entrada do seu código. Todo processamento de dados subsequente passa por essa sessão, que se comunica com o backend do MaxCompute.

    import os
from maxframe import new_session
from odps import ODPS

# Initialize MaxCompute with your credentials.
o = ODPS(
    os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
    os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
    project='your-default-project',
    endpoint='your-end-point',
)

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

    Para obter detalhes sobre os parâmetros, consulte MaxFrame-specific APIs.

    Criar um DataFrame

    Use read_odps_table ou read_odps_query para carregar dados do MaxCompute em um DataFrame do MaxFrame. Também é possível criar um DataFrame a partir de dados locais para testes rápidos.

    Ler dados de uma tabela do MaxCompute

    O método read_odps_table lê uma tabela do MaxCompute e retorna um DataFrame.

    import maxframe.dataframe as md

# Read all columns from the table.
df = md.read_odps_table('BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users')

    Use index_col para definir uma coluna como o índice do DataFrame, ou columns para selecionar um subconjunto de colunas:

    # Set user_id as the index.
df = md.read_odps_table(
    'BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users',
    index_col='user_id'
)

# Select specific columns.
df = md.read_odps_table(
    'BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users',
    columns=['user_id', 'age', 'sex']
)

    Para obter detalhes completos sobre os parâmetros, consulte MaxFrame-specific APIs.

    Ler dados de uma consulta SQL

    Execute uma consulta SQL e use o resultado como um DataFrame:

    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`'
)

# Optionally set the index column.
df = md.read_odps_query(
    'select user_id, age, sex FROM `BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users`',
    index_col='user_id'
)

    Para obter detalhes completos sobre os parâmetros, consulte MaxFrame-specific APIs.

    Criar a partir de dados locais

    Para testes locais rápidos, crie um DataFrame diretamente a partir de um dicionário do Python:

    import maxframe.dataframe as md

d = {'col1': [1, 2], 'col2': [3, 4]}
df = md.DataFrame(data=d)
print(df.execute().fetch())

# Result:
#    col1  col2
# 0     1     3
# 1     2     4

    Processar dados

    O MaxFrame suporta as mesmas operações de dados do Pandas. Todas as operações usam avaliação preguiçosa — encadeie quantas forem necessárias e, em seguida, chame o .execute() uma única vez para iniciar a computação.

    Operações matemáticas

    Aplique operações aritméticas por coluna. Todos os operadores padrão (+, -, *, /) funcionam como no Pandas.

    import maxframe.dataframe as md

df = md.DataFrame({'angles': [0, 3, 4],
                   'degrees': [360, 180, 360]},
                  index=['circle', 'triangle', 'rectangle'])

# Addition
print((df + 1).execute().fetch())
# Result:
#            angles  degrees
# circle          1      361
# triangle        4      181
# rectangle       5      361

# Multiplication
print((df * 2).execute().fetch())
# Result:
#            angles  degrees
# circle          0      720
# triangle        6      360
# rectangle       8      720

# Division
print((df / 2).execute().fetch())
# Result:
#            angles  degrees
# circle        0.0      180
# triangle      1.5       90
# rectangle     2.0      180

# Exponentiation
print((df ** 2).execute().fetch())
# Result:
#            angles  degrees
# circle          0   129600
# triangle        9    32400
# rectangle      16   129600

    Para mais informações, consulte Binary operator functions.

    Filtragem, projeção e amostragem

    Filtragem

    Selecione as linhas que atendem a uma condição:

    import maxframe.dataframe as md

df = md.read_odps_table('BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users')

# Keep only rows where age > 18.
filtered_df = df[df['age'] > 18]
print(filtered_df.execute().fetch())
# Result:
#    user_id  age sex occupation zip_code
# 0        1   24   M technician    85711
# 1        2   53   F      other    94043
# ...

    Projeção

    Selecione um subconjunto de colunas:

    import maxframe.dataframe as md

df = md.read_odps_table('BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users')

# Select specific columns.
projected_df = df[['user_id', 'age']]
print(projected_df.execute().fetch())
# Result:
#    user_id  age
# 0        1   24
# 1        2   53
# ...

    Amostragem

    Extraia uma amostra aleatória de um DataFrame:

    import maxframe.dataframe as md

df = md.DataFrame({'num_legs': [2, 4, 8, 0],
                   'num_wings': [2, 0, 0, 0],
                   'num_specimen_seen': [10, 2, 1, 8]},
                  index=['falcon', 'dog', 'spider', 'fish'])

print(df['num_legs'].sample(n=3, random_state=1).execute())
# Result:
# falcon    2
# fish      0
# dog       4
# Name: num_legs, dtype: int64

    Para mais informações, consulte Reindexing / selection / label manipulation.

    Ordenação

    Ordene um DataFrame por uma ou mais colunas usando sort_values:

    import maxframe.dataframe as md
import numpy as np

df = md.DataFrame({
    'col1': ['A', 'A', 'B', np.nan, 'D', 'C'],
    'col2': [2, 1, 9, 8, 7, 4],
    'col3': [0, 1, 9, 4, 2, 3],
})

# Sort by col1.
res = df.sort_values(by=['col1']).execute()
print(res.fetch())
# Result:
#    col1  col2  col3
# 0     A     2     0
# 1     A     1     1
# 2     B     9     9
# 5     C     4     3
# 4     D     7     2
# 3  None     8     4

# Sort by col1, then col2.
res = df.sort_values(by=['col1', 'col2']).execute()
print(res.fetch())
# Result:
#    col1  col2  col3
# 1     A     1     1
# 0     A     2     0
# 2     B     9     9
# 5     C     4     3
# 4     D     7     2
# 3  None     8     4

    Para mais informações, consulte Reshaping / sorting / transposing.

    Junção, mesclagem e concatenação

    Combine DataFrames horizontalmente (join/merge) ou verticalmente (concatenate).

    import maxframe.dataframe as md

df1 = md.DataFrame({'key': ['K0', 'K1', 'K2'],
                    'A': ['A0', 'A1', 'A2'],
                    'B': ['B0', 'B1', 'B2']})

df2 = md.DataFrame({'key': ['K0', 'K1', 'K2'],
                    'C': ['C0', 'C1', 'C2'],
                    'D': ['D0', 'D1', 'D2']})

# Merge on a key column.
result = md.merge(df1, df2, on='key')
print(result.execute().fetch())
# Result:
#   key   A   B   C   D
# 0  K0  A0  B0  C0  D0
# 1  K1  A1  B1  C1  D1
# 2  K2  A2  B2  C2  D2

# Concatenate vertically.
result = md.concat([df1, df2])
print(result.execute().fetch())

    Para mais informações, consulte Combining / joining / merging.

    Agregação e funções definidas pelo usuário (UDFs)

    Agregação

    Resuma dados por grupos ou colunas com funções de agregação:

    import maxframe.dataframe as md
import numpy as np

df = md.DataFrame([[1, 2, 3],
                   [4, 5, 6],
                   [7, 8, 9],
                   [np.nan, np.nan, np.nan]],
                  columns=['A', 'B', 'C'])

# Apply multiple aggregation functions.
print(df.agg(['sum', 'min']).execute().fetch())
# Result:
#         A     B     C
# min   1.0   2.0   3.0
# sum  12.0  15.0  18.0

# Apply different functions to different columns.
df.agg({'A': ['sum', 'min'], 'B': ['min', 'max']}).execute().fetch()
# Result:
#         A    B
# max   NaN  8.0
# min   1.0  2.0
# sum  12.0  NaN

    UDFs

    O MaxFrame suporta UDFs por meio de transform e apply. Use UDFs para lógica personalizada que os operadores integrados não cobrem.

    Importante

    Antes de executar uma UDF, declare a imagem comum (common image) definindo config.options.sql.settings antes de chamar new_session.

    Todos os exemplos de UDF usam este bloco de configuração:

    from maxframe import config
config.options.sql.settings = {
    "odps.session.image": "common",
    "odps.sql.type.system.odps2": "true"
}
session = new_session(o)

    Use transform para aplicar uma UDF por coluna (o formato de saída corresponde à entrada):

    import maxframe.dataframe as md

df = md.DataFrame({'A': range(3), 'B': range(1, 4)})
print(df.transform(lambda x: x + 1).execute().fetch())
# Result:
#    A  B
# 0  1  2
# 1  2  3
# 2  3  4

    Use apply quando o número de colunas de saída for diferente da entrada:

    import maxframe.dataframe as md
import numpy as np

def simple(row):
    row['is_man'] = row['sex'] == "man"
    return row

df = md.read_odps_table('BIGDATA_PUBLIC_DATASET.data_science.maxframe_ml_100k_users')
new_dtypes = df.dtypes.copy()
new_dtypes["is_man"] = np.dtype(np.bool_)

df.apply(
    simple,
    axis=1,
    result_type="expand",
    output_type="dataframe",
    dtypes=new_dtypes
).execute().fetch()
# Result:
#      user_id  age sex     occupation zip_code  is_man
# 0          1   24   M     technician    85711   False
# 1          2   53   F          other    94043   False
# ...
# [943 rows x 6 columns]

    Para mais informações, consulte Function application / GroupBy / window.

    Armazenar resultados

    Após o processamento, salve os resultados em uma tabela do MaxCompute com to_odps_table.

    # Write results to a MaxCompute table.
filtered_df.to_odps_table('<table_name>')

# Set a lifecycle (in days) for the result table.
filtered_df.to_odps_table('<table_name>', lifecycle=7)

    Parâmetro

    Descrição

    <table_name>

    Nome da tabela de destino. Se a tabela não existir, o MaxCompute a cria automaticamente. Se já existir, os dados são anexados por padrão.

    lifecycle

    Número de dias para reter a tabela de resultados.

    overwrite

    Defina como True para sobrescrever os dados existentes em vez de anexá-los.

    Para mais informações, consulte MaxFrame-specific APIs.

    Executar e recuperar resultados

    O MaxFrame usa avaliação preguiçosa — as operações constroem um grafo de computação, mas não são executadas até que você chame o .execute(). Encadeie .execute().fetch() para iniciar a execução e recuperar os resultados.

    # Execute the computation and fetch results.
data = filtered_df.execute().fetch()
print(data)

    Método

    Descrição

    .execute()

    Envia o grafo de computação para o MaxCompute e aguarda a conclusão.

    .fetch()

    Recupera uma parte dos dados de resultado após a execução.

    .execute().fetch()

    Inicia a execução e retorna os resultados em uma única etapa.

    Para mais informações, consulte MaxFrame-specific APIs e MaxFrame-specific APIs.