Acesso a dados em blocos de anotações do Jupyterlab

Cada kernel suportado fornece funcionalidades integradas que permitem ler os dados da plataforma de um conjunto de dados em um notebook. Atualmente, o JupyterLab na Adobe Experience Platform Data Science Workspace oferece suporte a notebooks para Python, R, PySpark e Scala. No entanto, o suporte para dados de paginação é limitado a blocos de anotações do Python e R. Este guia tem como foco o uso de notebooks JupyterLab para acessar seus dados.

Introdução

Antes de ler este guia, consulte o JupyterLab guia do usuário para obter uma introdução geral sobre o JupyterLab e sua função no Data Science Workspace.

Limites de dados de notebook notebook-data-limits

As informações a seguir definem a quantidade máxima de dados que podem ser lidos, que tipo de dados foi usado e o período estimado para ler os dados.

Para Python e R, um servidor notebook configurado com 40 GB de RAM foi usado para os benchmarks. Para o PySpark e Scala, um cluster de databricks configurado em 64 GB de RAM, 8 núcleos, 2 DBUs com um máximo de 4 trabalhadores foi usado para os benchmarks descritos abaixo.

Os dados do esquema ExperienceEvent usados variaram em tamanho, começando em mil (1K) linhas, variando até um bilhão (1B) de linhas. Observe que para as métricas PySpark e Spark, um intervalo de data de 10 dias foi usado para os dados XDM.

Os dados do esquema ad-hoc foram pré-processados usando o Query Service Criar Tabela como Seleção (CTAS). Esses dados também variaram em tamanho, começando com mil (1K) linhas variando até um bilhão (1B) de linhas.

Quando usar o modo de lote vs. modo interativo mode

Ao ler conjuntos de dados com notebooks PySpark e Scala, você tem a opção de usar o modo interativo ou o modo em lote para ler o conjunto de dados. Interativo é feito para resultados rápidos, enquanto o modo de lote é para conjuntos de dados grandes.

Python limites de dados do bloco de anotações

Esquema XDM ExperienceEvent: Você deve ser capaz de ler um máximo de 2 milhões de linhas (aproximadamente 6,1 GB de dados no disco) de dados XDM em menos de 22 minutos. A adição de linhas adicionais pode resultar em erros.

esquema ad-hoc: Você deverá conseguir ler um máximo de 5 milhões de linhas (aproximadamente 5,6 GB de dados no disco) de dados não XDM (ad-hoc) em menos de 14 minutos. A adição de linhas adicionais pode resultar em erros.

Limites de dados do bloco de anotações R

Esquema XDM ExperienceEvent: Você deve ser capaz de ler no máximo 1 milhão de linhas de dados XDM (dados de 3 GB no disco) em menos de 13 minutos.

esquema ad-hoc: Você deverá ler no máximo 3 milhões de linhas de dados ad-hoc (293 MB de dados no disco) em cerca de 10 minutos.

Limites de dados de bloco de anotações do PySpark (Python kernel): pyspark-data-limits

Esquema XDM ExperienceEvent: No modo interativo, você deve ler um máximo de 5 milhões de linhas (aproximadamente 13,42 GB de dados no disco) de dados XDM em cerca de 20 minutos. O modo interativo suporta apenas até 5 milhões de linhas. Se você quiser ler conjuntos de dados maiores, sugerimos mudar para o modo de lote. No modo de lote, você deve ser capaz de ler um máximo de 500 milhões de linhas (aproximadamente 1,31 TB de dados no disco) de dados XDM em cerca de 14 horas.

esquema ad-hoc: No modo Interativo, você poderá ler um máximo de 5 milhões de linhas (aproximadamente 5,36 GB de dados no disco) de dados não XDM em menos de 3 minutos. No modo de Lote, você deve ser capaz de ler no máximo 1 bilhão de linhas (aproximadamente 1,05 TB de dados no disco) de dados não XDM em cerca de 18 minutos.

Limites de dados de bloco de anotações Spark (kernel Scala): scala-data-limits

Esquema XDM ExperienceEvent: No modo interativo, você deve ler um máximo de 5 milhões de linhas (aproximadamente 13,42 GB de dados no disco) de dados XDM em cerca de 18 minutos. O modo interativo suporta apenas até 5 milhões de linhas. Se você quiser ler conjuntos de dados maiores, sugerimos mudar para o modo de lote. No modo de lote, você deve ser capaz de ler um máximo de 500 milhões de linhas (aproximadamente 1,31 TB de dados no disco) de dados XDM em cerca de 14 horas.

esquema ad-hoc: No modo interativo, você poderá ler um máximo de 5 milhões de linhas (aproximadamente 5,36 GB de dados no disco) de dados não XDM em menos de 3 minutos. No modo de lote, você deve ser capaz de ler no máximo 1 bilhão de linhas (aproximadamente 1,05 TB de dados no disco) de dados não XDM em cerca de 16 minutos.

Blocos de anotações Python python-notebook

Os blocos de anotações do Python permitem que você pagine dados ao acessar conjuntos de dados. A amostra de código para ler dados com e sem paginação é demonstrada abaixo. Para obter mais informações sobre os notebooks Python iniciais disponíveis, visite a seção JupyterLab Iniciador no guia do usuário do JupyterLab.

A documentação do Python abaixo descreve os seguintes conceitos:

Ler de um conjunto de dados no Python python-read-dataset

Sem paginação:

A execução do código a seguir lerá todo o conjunto de dados. Se a execução for bem-sucedida, os dados serão salvos como um quadro de dados Pandas referenciado pela variável df.

# Python

from platform_sdk.dataset_reader import DatasetReader
dataset_reader = DatasetReader(get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df = dataset_reader.read()
df.head()

Com paginação:

A execução do código a seguir lerá os dados do conjunto de dados especificado. A paginação é alcançada limitando e deslocando dados através das funções limit() e offset() respectivamente. A limitação de dados refere-se ao número máximo de pontos de dados a serem lidos, enquanto a compensação se refere ao número de pontos de dados a serem ignorados antes da leitura dos dados. Se a operação de leitura for executada com êxito, os dados serão salvos como um quadro de dados Pandas referenciado pela variável df.

# Python

from platform_sdk.dataset_reader import DatasetReader

dataset_reader = DatasetReader(get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df = dataset_reader.limit(100).offset(10).read()

Gravar em um conjunto de dados no Python write-python

Para gravar em um conjunto de dados no notebook JupyterLab, selecione a guia Data icon (destacada abaixo) na navegação à esquerda do JupyterLab. Os diretórios Datasets e Schemas são exibidos. Selecione Conjuntos de Dados, clique com o botão direito do mouse e selecione a opção Gravar Dados no Bloco de Anotações no menu suspenso do conjunto de dados que você deseja usar. Uma entrada de código executável é exibida na parte inferior do bloco de anotações.

Como alternativa, você pode copiar e colar a seguinte célula de código. Substitua {DATASET_ID} e {PANDA_DATAFRAME}.

from platform_sdk.models import Dataset
from platform_sdk.dataset_writer import DatasetWriter

dataset = Dataset(get_platform_sdk_client_context()).get_by_id(dataset_id="{DATASET_ID}")
dataset_writer = DatasetWriter(get_platform_sdk_client_context(), dataset)
write_tracker = dataset_writer.write({PANDA_DATAFRAME}, file_format='json')

Consultar dados usando Query Service em Python query-data-python

JupyterLab em Platform permite que você use o SQL em um bloco de anotações Python para acessar dados por meio do Serviço de Consulta Adobe Experience Platform. O acesso aos dados por meio do Query Service pode ser útil para lidar com grandes conjuntos de dados devido aos seus tempos de execução superiores. Observe que a consulta de dados usando o Query Service tem um limite de tempo de processamento de dez minutos.

Antes de usar Query Service em JupyterLab, verifique se você tem uma compreensão funcional da Query Service sintaxe SQL.

A consulta de dados usando Query Service exige que você forneça o nome do conjunto de dados de destino. Você pode gerar as células de código necessárias localizando o conjunto de dados desejado usando o Data Explorer. Clique com o botão direito do mouse na lista do conjunto de dados e clique em Consultar Dados no Bloco de Anotações para gerar duas células de código no seu bloco de anotações. Estas duas células são descritas em mais detalhes abaixo.

Para utilizar o Query Service no JupyterLab, primeiro você deve criar uma conexão entre o bloco de anotações Python de trabalho e o Query Service. Isso pode ser feito executando a primeira célula gerada.

qs_connect()

Na segunda célula gerada, a primeira linha deve ser definida antes da consulta SQL. Por padrão, a célula gerada define uma variável opcional (df0) que salva os resultados da consulta como um quadro de dados Pandas.
O argumento -c QS_CONNECTION é obrigatório e informa ao kernel para executar a consulta SQL em Query Service. Consulte o apêndice para obter uma lista de argumentos adicionais.

%%read_sql df0 -c QS_CONNECTION
SELECT *
FROM name_of_the_dataset
LIMIT 10
/* Querying table "name_of_the_dataset" (datasetId: {DATASET_ID})*/

As variáveis Python podem ser referenciadas diretamente em uma consulta SQL usando uma sintaxe formatada em sequência e unindo as variáveis entre chaves ({}), conforme mostrado no exemplo a seguir:

table_name = 'name_of_the_dataset'
table_columns = ','.join(['col_1','col_2','col_3'])

%%read_sql demo -c QS_CONNECTION
SELECT {table_columns}
FROM {table_name}

Filtrar dados de ExperienceEvent python-filter

Para acessar e filtrar um conjunto de dados ExperienceEvent em um bloco de anotações Python, você deve fornecer a ID do conjunto de dados ({DATASET_ID}) juntamente com as regras de filtro que definem um intervalo de tempo específico usando operadores lógicos. Quando um intervalo de tempo é definido, qualquer paginação especificada é ignorada e todo o conjunto de dados é considerado.

Uma lista de operadores de filtragem é descrita abaixo:

A célula a seguir filtra um conjunto de dados ExperienceEvent para dados existentes exclusivamente entre 1º de janeiro de 2019 e o final de 31 de dezembro de 2019.

# Python

from platform_sdk.dataset_reader import DatasetReader

dataset_reader = DatasetReader(get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df = dataset_reader.\
    where(dataset_reader["timestamp"].gt("2019-01-01 00:00:00").\
    And(dataset_reader["timestamp"].lt("2019-12-31 23:59:59"))\
).read()

Blocos de anotações R r-notebooks

Os blocos de anotações R permitem paginar dados ao acessar conjuntos de dados. A amostra de código para ler dados com e sem paginação é demonstrada abaixo. Para obter mais informações sobre os notebooks iniciais R disponíveis, visite a seção JupyterLab Iniciador no guia do usuário do JupyterLab.

A documentação do R abaixo descreve os seguintes conceitos:

Ler de um conjunto de dados no R r-read-dataset

Sem paginação:

A execução do código a seguir lerá todo o conjunto de dados. Se a execução for bem-sucedida, os dados serão salvos como um quadro de dados Pandas referenciado pela variável df0.

# R

library(reticulate)
use_python("/usr/local/bin/ipython")
psdk <- import("platform_sdk")
datetime <- import("datetime", convert = FALSE)
py_run_file("~/.ipython/profile_default/startup/platform_sdk_context.py")
DatasetReader <- psdk$dataset_reader$DatasetReader
dataset_reader <- DatasetReader(py$get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df0 <- dataset_reader$read()
head(df0)

Com paginação:

A execução do código a seguir lerá os dados do conjunto de dados especificado. A paginação é alcançada limitando e deslocando dados através das funções limit() e offset() respectivamente. A limitação de dados refere-se ao número máximo de pontos de dados a serem lidos, enquanto a compensação se refere ao número de pontos de dados a serem ignorados antes da leitura dos dados. Se a operação de leitura for executada com êxito, os dados serão salvos como um quadro de dados Pandas referenciado pela variável df0.

# R

library(reticulate)
use_python("/usr/local/bin/ipython")
psdk <- import("platform_sdk")
datetime <- import("datetime", convert = FALSE)
py_run_file("~/.ipython/profile_default/startup/platform_sdk_context.py")

DatasetReader <- psdk$dataset_reader$DatasetReader
dataset_reader <- DatasetReader(py$get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")
df0 <- dataset_reader$limit(100L)$offset(10L)$read()

Gravar em um conjunto de dados no R write-r

Para gravar em um conjunto de dados no notebook JupyterLab, selecione a guia Data icon (destacada abaixo) na navegação à esquerda do JupyterLab. Os diretórios Datasets e Schemas são exibidos. Selecione Conjuntos de Dados, clique com o botão direito do mouse e selecione a opção Gravar Dados no Bloco de Anotações no menu suspenso do conjunto de dados que você deseja usar. Uma entrada de código executável é exibida na parte inferior do bloco de anotações.

Como alternativa, você pode copiar e colar a seguinte célula de código:

psdk <- import("platform_sdk")
dataset <- psdk$models$Dataset(py$get_platform_sdk_client_context())$get_by_id(dataset_id="{DATASET_ID}")
dataset_writer <- psdk$dataset_writer$DatasetWriter(py$get_platform_sdk_client_context(), dataset)
write_tracker <- dataset_writer$write(df, file_format='json')

Filtrar dados de ExperienceEvent r-filter

Para acessar e filtrar um conjunto de dados ExperienceEvent em um bloco de anotações R, você deve fornecer a ID do conjunto de dados ({DATASET_ID}) juntamente com as regras de filtro que definem um intervalo de tempo específico usando operadores lógicos. Quando um intervalo de tempo é definido, qualquer paginação especificada é ignorada e todo o conjunto de dados é considerado.

Uma lista de operadores de filtragem é descrita abaixo:

A célula a seguir filtra um conjunto de dados ExperienceEvent para dados existentes exclusivamente entre 1º de janeiro de 2019 e o final de 31 de dezembro de 2019.

# R

library(reticulate)
use_python("/usr/local/bin/ipython")
psdk <- import("platform_sdk")
datetime <- import("datetime", convert = FALSE)
py_run_file("~/.ipython/profile_default/startup/platform_sdk_context.py")

client_context <- py$PLATFORM_SDK_CLIENT_CONTEXT
DatasetReader <- psdk$dataset_reader$DatasetReader
dataset_reader <- DatasetReader(py$get_platform_sdk_client_context(), dataset_id="{DATASET_ID}")

df0 <- dataset_reader$
    where(dataset_reader["timestamp"]$gt("2019-01-01 00:00:00")$
    And(dataset_reader["timestamp"]$lt("2019-12-31 23:59:59"))
)$read()

Notebooks PySpark 3 pyspark-notebook

A documentação do PySpark abaixo descreve os seguintes conceitos:

Inicializando sparkSession spark-initialize

Todos os blocos de anotações do Spark 2.4 exigem que você inicialize a sessão com o seguinte código padrão.

from pyspark.sql import SparkSession
spark = SparkSession.builder.getOrCreate()

Usando o conjunto de dados %s para ler e gravar com um bloco de anotações do PySpark 3 magic

Com a introdução do Spark 2.4, a mágica personalizada do %dataset é fornecida para uso nos notebooks PySpark 3 (Spark 2.4). Para obter mais detalhes sobre comandos mágicos disponíveis no kernel IPython, visite a documentação mágica do IPython.

Uso

%dataset {action} --datasetId {id} --dataFrame {df} --mode batch

Descrição

Um comando mágico Data Science Workspace personalizado para ler ou gravar um conjunto de dados de um bloco de anotações PySpark (Python 3 kernel).

Exemplos

Você pode gerar automaticamente os exemplos acima na compra do JupyterLab usando o seguinte método:

Selecione a guia Data icon (destacada abaixo) no menu de navegação esquerdo do JupyterLab. Os diretórios Datasets e Schemas são exibidos. Selecione Conjuntos de Dados, clique com o botão direito do mouse e selecione a opção Gravar Dados no Bloco de Anotações no menu suspenso do conjunto de dados que você deseja usar. Uma entrada de código executável é exibida na parte inferior do bloco de anotações.

Criar um quadro de dados local pyspark-create-dataframe

Para criar um quadro de dados local usando o PySpark 3, use queries SQL. Por exemplo:

date_aggregation.createOrReplaceTempView("temp_df")

df = spark.sql('''
  SELECT *
  FROM sparkdf
''')

local_df

df = spark.sql('''
  SELECT *
  FROM sparkdf
  LIMIT limit
''')

sample_df = df.sample(fraction)

Filtrar dados de ExperienceEvent pyspark-filter-experienceevent

Para acessar e filtrar um conjunto de dados ExperienceEvent em um bloco de anotações do PySpark, é necessário fornecer a identidade do conjunto de dados ({DATASET_ID}), a identidade IMS da organização e as regras de filtro que definem um intervalo de tempo específico. Um intervalo de tempo de filtragem é definido com a função spark.sql(), na qual o parâmetro da função é uma cadeia de caracteres de consulta SQL.

As células a seguir filtram um conjunto de dados ExperienceEvent para dados existentes exclusivamente entre 1º de janeiro de 2019 e o final de 31 de dezembro de 2019.

# PySpark 3 (Spark 2.4)

from pyspark.sql import SparkSession
spark = SparkSession.builder.getOrCreate()

%dataset read --datasetId {DATASET_ID} --dataFrame df --mode batch

df.createOrReplaceTempView("event")
timepd = spark.sql("""
    SELECT *
    FROM event
    WHERE timestamp > CAST('2019-01-01 00:00:00.0' AS TIMESTAMP)
    AND timestamp < CAST('2019-12-31 23:59:59.9' AS TIMESTAMP)
""")
timepd.show()

Notebooks Scala scala-notebook

A documentação abaixo contém exemplos dos seguintes conceitos:

Inicializando SparkSession scala-initialize

Todos os blocos de anotações Scala exigem que você inicialize a sessão com o seguinte código padrão:

import org.apache.spark.sql.{ SparkSession }
val spark = SparkSession
  .builder()
  .master("local")
  .getOrCreate()

Ler um conjunto de dados read-scala-dataset

No Scala, você pode importar clientContext para obter e retornar valores da Platform, o que elimina a necessidade de definir variáveis como var userToken. No exemplo da Escala abaixo, clientContext é usado para obter e retornar todos os valores necessários para ler um conjunto de dados.

import org.apache.spark.sql.{Dataset, SparkSession}
import com.adobe.platform.token.ClientContext
val spark = SparkSession.builder().master("local").config("spark.sql.warehouse.dir", "/").getOrCreate()

val clientContext = ClientContext.getClientContext()
val df1 = spark.read.format("com.adobe.platform.query")
  .option("user-token", clientContext.getUserToken())
  .option("ims-org", clientContext.getOrgId())
  .option("api-key", clientContext.getApiKey())
  .option("service-token", clientContext.getServiceToken())
  .option("sandbox-name", clientContext.getSandboxName())
  .option("mode", "batch")
  .option("dataset-id", "5e68141134492718af974844")
  .load()

df1.printSchema()
df1.show(10)

Você pode gerar automaticamente o exemplo acima na compra do JupyterLab usando o seguinte método:

Selecione a guia Data icon (destacada abaixo) no menu de navegação esquerdo do JupyterLab. Os diretórios Datasets e Schemas são exibidos. Selecione Conjuntos de Dados, clique com o botão direito do mouse e selecione a opção Explorar Dados no Bloco de Anotações no menu suspenso do conjunto de dados que você deseja usar. Uma entrada de código executável é exibida na parte inferior do bloco de anotações.
E

Gravar em um conjunto de dados scala-write-dataset

No Scala, você pode importar clientContext para obter e retornar valores da Platform, o que elimina a necessidade de definir variáveis como var userToken. No exemplo de Escala abaixo, clientContext é usado para definir e retornar todos os valores necessários para gravar em um conjunto de dados.

import org.apache.spark.sql.{Dataset, SparkSession}
import com.adobe.platform.token.ClientContext
val spark = SparkSession.builder().master("local").config("spark.sql.warehouse.dir", "/").getOrCreate()

val clientContext = ClientContext.getClientContext()
df1.write.format("com.adobe.platform.query")
  .option("user-token", clientContext.getUserToken())
  .option("service-token", clientContext.getServiceToken())
  .option("ims-org", clientContext.getOrgId())
  .option("api-key", clientContext.getApiKey())
  .option("sandbox-name", clientContext.getSandboxName())
  .option("mode", "batch")
  .option("dataset-id", "5e68141134492718af974844")
  .save()

criar um quadro de dados local scala-create-dataframe

Para criar um quadro de dados local usando o Scala, são necessárias consultas SQL. Por exemplo:

sparkdf.createOrReplaceTempView("sparkdf")

val localdf = spark.sql("SELECT * FROM sparkdf LIMIT 1)

Filtrar dados de ExperienceEvent scala-experienceevent

Para acessar e filtrar um conjunto de dados ExperienceEvent em um bloco de anotações Scala, é necessário fornecer a identidade do conjunto de dados ({DATASET_ID}), a identidade IMS da sua organização e as regras de filtro que definem um intervalo de tempo específico. Um intervalo de tempo de Filtragem é definido com o uso da função spark.sql(), na qual o parâmetro da função é uma cadeia de caracteres de consulta SQL.

As células a seguir filtram um conjunto de dados ExperienceEvent para dados existentes exclusivamente entre 1º de janeiro de 2019 e o final de 31 de dezembro de 2019.

// Spark (Spark 2.4)

// Turn off extra logging
import org.apache.log4j.{Level, Logger}
Logger.getLogger("org").setLevel(Level.OFF)
Logger.getLogger("com").setLevel(Level.OFF)

import org.apache.spark.sql.{Dataset, SparkSession}
val spark = org.apache.spark.sql.SparkSession.builder().appName("Notebook")
  .master("local")
  .getOrCreate()

// Stage Exploratory
val dataSetId: String = "{DATASET_ID}"
val orgId: String = sys.env("IMS_ORG_ID")
val clientId: String = sys.env("PYDASDK_IMS_CLIENT_ID")
val userToken: String = sys.env("PYDASDK_IMS_USER_TOKEN")
val serviceToken: String = sys.env("PYDASDK_IMS_SERVICE_TOKEN")
val mode: String = "batch"

var df = spark.read.format("com.adobe.platform.query")
  .option("user-token", userToken)
  .option("ims-org", orgId)
  .option("api-key", clientId)
  .option("mode", mode)
  .option("dataset-id", dataSetId)
  .option("service-token", serviceToken)
  .load()
df.createOrReplaceTempView("event")
val timedf = spark.sql("""
    SELECT *
    FROM event
    WHERE timestamp > CAST('2019-01-01 00:00:00.0' AS TIMESTAMP)
    AND timestamp < CAST('2019-12-31 23:59:59.9' AS TIMESTAMP)
""")
timedf.show()

Próximas etapas

Esse documento abordou as diretrizes gerais para acessar conjuntos de dados usando notebooks JupyterLab. Para obter exemplos mais detalhados sobre consulta de conjuntos de dados, visite a documentação do Serviço de consulta em notebooks JupyterLab. Para obter mais informações sobre como explorar e visualizar seus conjuntos de dados, visite o documento em analisando seus dados usando blocos de anotações.

Sinalizadores SQL opcionais para Query Service optional-sql-flags-for-query-service

Esta tabela descreve os sinalizadores SQL opcionais que podem ser usados para Query Service.