Acesso a dados em blocos de anotações Jupyterlab

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

Introdução

Antes de ler este guia, revise o JupyterLab guia do usuário para obter uma introdução de alto nível a JupyterLab e sua função no Data Science Workspace.

Limites de dados do notebook

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

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

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

Os dados do esquema ad-hoc foram pré-processados usando Query Service Criar tabela como seleção (CTAS). Esses dados também variaram em tamanho a partir de mil linhas (1.000) que variam de até um bilhão (1B) de linhas.

Quando usar o modo de lote vs. o modo interativo

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

• Para notebooks PySpark e Scala, o modo de lote deve ser usado quando 5 milhões de linhas de dados ou mais estão sendo lidas. Para obter mais informações sobre a eficiência de cada modo, consulte as tabelas de limite de dados PySpark ou Scala abaixo.

Python limites de dados do notebook

Esquema XDM ExperienceEvent: você deve ser capaz de ler no máximo 2 milhões de linhas (~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ê deve ser capaz de ler no máximo 5 milhões de linhas (~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 notebook R

Esquema XDM ExperienceEvent: você deve conseguir 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ê deve conseguir ler no máximo 3 milhões de linhas de dados ad-hoc (dados de 293 MB em disco) em aproximadamente 10 minutos.

Limites de dados do bloco de notas PySpark (Python kernel):

Esquema XDM ExperienceEvent: no modo interativo, você deve ser capaz de ler no máximo 5 milhões de linhas (~13,42 GB de dados no disco) dos dados XDM em cerca de 20 minutos. O modo interativo suporta apenas até 5 milhões de linhas. Caso deseje ler conjuntos de dados maiores, sugerimos que você alterne para o modo de lote. No modo de lote, é possível ler no máximo 500 milhões de linhas (~1,31 TB de dados no disco) de dados XDM em cerca de 14 horas.

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

Spark Limites de dados do notebook (kernel Scala):

Esquema XDM ExperienceEvent: no modo interativo, você deve ser capaz de ler no máximo 5 milhões de linhas (~13,42 GB de dados no disco) dos dados XDM em cerca de 18 minutos. O modo interativo suporta apenas até 5 milhões de linhas. Caso deseje ler conjuntos de dados maiores, sugerimos que você alterne para o modo de lote. No modo de lote, é possível ler no máximo 500 milhões de linhas (~1,31 TB de dados no disco) de dados XDM em cerca de 14 horas.

esquema ad-hoc: no modo interativo, você deve ser capaz de ler no máximo 5 milhões de linhas (~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 (~1,05 TB de dados no disco) de dados não-XDM em cerca de 16 minutos.

Notebooks Python

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

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

• Ler a partir de um conjunto de dados
• Gravar em um conjunto de dados
• Consultar dados
• Filtrar dados do ExperienceEvent

Ler de um conjunto de dados em Python

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 dataframe de Paindas 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 compensando dados por meio 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 refere-se 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 dataframe de 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 em Python

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

• Use Write Data in Notebook para gerar uma célula de gravação com o conjunto de dados selecionado.
• Use Explorar dados no notebook para gerar uma célula de leitura com seu conjunto de dados selecionado.
• Use Dados de consulta no Bloco de notas para gerar uma célula de consulta básica com o conjunto de dados selecionado.

Como alternativa, você pode copiar e colar a seguinte célula de código. Substitua o {DATASET_ID} e o {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

JupyterLab O on Platform permite usar o SQL em um Python notebook para acessar dados por meio do Adobe Experience Platform Query Service. O acesso aos dados por meio de Query Service pode ser útil para lidar com grandes conjuntos de dados devido aos tempos de execução superiores. Observe que a consulta de dados usando Query Service tem um limite de tempo de processamento de dez minutos.

Antes de usar Query Service em JupyterLab, certifique-se de ter uma compreensão funcional da Query Service sintaxe SQL.

Consultar dados usando Query Service requer 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 na listagem do conjunto de dados e clique em Consultar dados no bloco de notas para gerar duas células de código no bloco de notas. Essas duas células são descritas com mais detalhes abaixo.

Para utilizar Query Service em JupyterLab, primeiro você deve criar uma conexão entre o seu notebook de trabalho Python e Query Service. Isso pode ser feito executando-se 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 dataframe de Pandas.
O -c QS_CONNECTION argumento é obrigatório e informa ao kernel para executar a consulta SQL no 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 envolvendo as variáveis entre colchetes ({}), 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 ExperienceEvent

Para acessar e filtrar um conjunto de dados ExperienceEvent em um bloco de notas 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:

• eq(): Equal to
• gt(): Greater than
• ge(): Greater than or equal to
• lt(): Less than
• le(): Less than or equal to
• And(): Operador AND lógico
• Or(): Operador OR lógico

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

R blocos de anotações

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

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

• Ler a partir de um conjunto de dados
• Gravar em um conjunto de dados
• Filtrar dados do ExperienceEvent

Ler de um conjunto de dados em R

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 dataframe de Paindas 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 compensando dados por meio 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 refere-se 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 dataframe de 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 em R

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

• Use Write Data in Notebook para gerar uma célula de gravação com o conjunto de dados selecionado.
• Use Explorar dados no notebook para gerar uma célula de leitura com seu conjunto de dados selecionado.

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 ExperienceEvent

Para acessar e filtrar um conjunto de dados ExperienceEvent em um bloco de dados 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:

• eq(): Igual a
• gt(): Maior que
• ge(): Maior que ou igual a
• lt(): Menor que
• le(): Menor que ou igual a
• And(): Operador AND lógico
• Or(): Operador OR lógico

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

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

• Inicializar sparkSession
• Ler e gravar dados
• Criar um dataframe local
• Filtrar dados do ExperienceEvent

Inicializando sparkSession

Todos os notebooks Spark 2.4 exigem que você inicialize a sessão com o seguinte código estereotipado.

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

Utilizando %dataset para ler e escrever com um bloco de notas PySpark 3

Com a introdução de Spark 2.4, %dataset mágica personalizada é fornecida para uso em notebooks PySpark 3 (Spark 2.4). Para obter mais detalhes sobre comandos mágicos disponíveis no kernel do 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

• Exemplo de leitura: %dataset read --datasetId 5e68141134492718af974841 --dataFrame pd0 --mode batch
• Exemplo de gravação: %dataset write --datasetId 5e68141134492718af974842 --dataFrame pd0 --mode batch

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

Selecione a guia Data icon (destacada abaixo) na navegação à esquerda do JupyterLab. Os diretórios Datasets e Schemas são exibidos. Selecione Datasets e clique com o botão direito do mouse e selecione a opção Write Data in Notebook no menu suspenso do conjunto de dados que deseja usar. Uma entrada de código executável é exibida na parte inferior do notebook.

• Use Explorar dados no notebook para gerar uma célula de leitura.
• Use Write Data in Notebook para gerar uma célula de gravação.

Criar um dataframe local

Para criar um dataframe local usando 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 ExperienceEvent

Acessar e filtrar um conjunto de dados ExperienceEvent em um notebook PySpark requer que você forneça a identidade do conjunto de dados ({DATASET_ID}), a identidade IMS de sua organização e as regras de filtro que definem um intervalo de tempo específico. Um intervalo de tempo de filtragem é definido usando a função spark.sql(), onde o parâmetro da função é uma string 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()

Blocos de anotações escaláveis

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

• Inicializar sparkSession
• Ler um conjunto de dados
• Gravar em um conjunto de dados
• Criar um dataframe local
• Filtrar dados do ExperienceEvent

Inicializando SparkSession

Todos os notebooks Scala exigem que você inicialize a sessão com o seguinte código estereotipado:

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

Ler um conjunto de dados

No Scala, é possível importar clientContext para obter e retornar valores da Plataforma, isso elimina a necessidade de definir variáveis como var userToken. No exemplo Scala 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) na navegação à esquerda do JupyterLab. Os diretórios Datasets e Schemas são exibidos. Selecione Datasets e clique com o botão direito do mouse e selecione a opção Explorar dados no notebook no menu suspenso do conjunto de dados que deseja usar. Uma entrada de código executável é exibida na parte inferior do notebook.
E

• Use Explorar dados no notebook para gerar uma célula de leitura.
• Use Write Data in Notebook para gerar uma célula de gravação.

Gravar em um conjunto de dados

No Scala, é possível importar clientContext para obter e retornar valores da Plataforma, isso elimina a necessidade de definir variáveis como var userToken. No exemplo Scala 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 dataframe local

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

sparkdf.createOrReplaceTempView("sparkdf")

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

Filtrar dados ExperienceEvent

Acessar e filtrar um conjunto de dados ExperienceEvent em um notebook Scala requer que você forneça a identidade do conjunto de dados ({DATASET_ID}), a identidade IMS de sua organização e as regras de filtro que definem um intervalo de tempo específico. Um intervalo de tempo Filtering é definido usando a função spark.sql(), onde o parâmetro de função é uma string 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

Este documento cobriu as diretrizes gerais para acessar conjuntos de dados usando notebooks JupyterLab. Para obter exemplos mais aprofundados sobre como consultar conjuntos de dados, visite a documentação Serviço de query nos notebooks JupyterLab. Para obter mais informações sobre como explorar e visualizar seus conjuntos de dados, visite o documento em analisar seus dados usando notebooks.

Sinalizadores SQL opcionais para Query Service

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