Communitygithub.com

Spark & PySpark

Escreve e ajusta jobs PySpark — estratégias de join, limites de broadcast, dimensionamento de shuffle partitions, diagnóstico e correção de skew, eliminação de UDFs, cache e layout de arquivos de saída — com limites concretos de tamanho e skew.

O que é Spark & PySpark?

Esta skill é um guia especializado para diagnosticar e otimizar jobs PySpark, focando nas três causas mais comuns de lentidão: shuffles evitáveis, chaves desbalanceadas (skew) e processamento linha a linha via Python. Ela ensina a analisar o plano de execução (explain) e a interface do Spark UI antes de ajustar o cluster, evitando o erro caro de aumentar recursos sem corrigir o DAG ineficiente. A skill cobre desde a configuração inicial da sessão Spark (como habilitar Adaptive Query Execution e definir spark.sql.shuffle.partitions baseado no tamanho dos dados) até técnicas avançadas como broadcast de tabelas pequenas, diagnóstico de skew com limites mensuráveis (partição >5x a mediana e >256 MB), salting de chaves quentes e escolha entre repartition e coalesce para layout de saída. Inclui um exemplo prático detalhado comparando uma abordagem ruim (join sort-merge com UDF Python) com uma otimizada (broadcast, filtros antecipados, funções nativas) e estabelece uma barra de qualidade clara: cada join deve ter sua estratégia justificada por evidências de tamanho, nenhuma UDF escalar Python deve sobreviver onde existe função embutida, e o plano final deve confirmar o plano pretendido. A skill é direcionada para desenvolvedores que perguntam "por que meu job Spark está lento", "devo fazer broadcast deste join", "uma tarefa demora para sempre enquanto as outras terminam" ou "meu job estoura memória durante um join", e também para quem está escrevendo novos jobs PySpark ETL. Não deve ser usada para design de tópicos Kafka, grupos de consumidores ou pipelines de streaming (use kafka-pipelines), nem para trabalho com DataFrames em máquina única que cabem em memória (use pandas-expert).

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SkillMedev/skills/tree/HEAD/skills/spark-jobs

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Spark & PySpark faz?

Quase todo job Spark lento é lento por uma de três razões: um shuffle evitável, uma chave desbalanceada (skew) ou linhas vazando pelo Python uma a uma. O erro custoso é ajustar o tamanho do cluster antes de ler o plano — pagar por mais executores para executar o mesmo DAG ineficiente mais rápido.

Procedimento operacional

Etapa 1: Coletar entradas

  1. O código do job e, para um job lento, a visualização da Spark UI do estágio lento (distribuição da duração das tarefas, tamanhos de leitura/escrita de shuffle) e a saída de df.explain(True).
  2. Tamanho e formato dos dados de entrada, e os tamanhos de ambos os lados de cada join.
  3. Configuração do cluster: número de executores, núcleos e memória.
  4. Se o job é uma nova criação ou um ajuste — para ajuste, diagnostique a partir do plano antes de tocar no código.

Etapa 2: Começar com uma sessão adequada

from pyspark.sql import SparkSession
from pyspark.sql import functions as F

spark = (
    SparkSession.builder
    .appName("etl")
    .config("spark.sql.shuffle.partitions", "200")
    .config("spark.sql.adaptive.enabled", "true")
    .getOrCreate()
)

Habilite a Adaptive Query Execution (AQE); ela coalesce partições de shuffle e altera estratégias de join em tempo de execução. Em seguida, dimensione spark.sql.shuffle.partitions deliberadamente: aponte para 100-200 MB por partição de shuffle, então partições ≈ dado de shuffle ÷ 128 MB, e no mínimo 2-3x o total de núcleos de executores para que nenhum núcleo fique ocioso.

Etapa 3: Permanecer na API DataFrame e fora do Python

Operações com DataFrame passam pelo Catalyst e Tungsten, proporcionando otimização de consulta e memória off-heap. Desça para RDDs apenas quando não existir primitiva de DataFrame. UDFs Python serializam cada linha para o worker Python e de volta, quebrando a geração de código. Ordem de preferência:

  1. Funções embutidas pyspark.sql.functions (ex.: F.regexp_extract, F.when).
  2. UDFs Pandas (vetorizadas) quando Python for inevitável.
  3. UDFs Python escalares apenas como último recurso.
from pyspark.sql.functions import pandas_udf

@pandas_udf("double")
def normalize(s):
    return (s - s.mean()) / s.std()

Etapa 4: Escolher a estratégia de join pelo tamanho

  • Faça broadcast do lado menor quando ele couber em memória. Spark faz broadcast automático abaixo de spark.sql.autoBroadcastJoinThreshold (padrão 10 MB); faça broadcast explícito de tabelas de até algumas centenas de MB quando a memória do executor permitir, e trate ~1 GB como o teto prático — broadcast copia a tabela para cada executor e causa OOM no job quando mal avaliado.
from pyspark.sql.functions import broadcast
result = large.join(broadcast(small), "key")
  • Filtre e projete colunas antes de fazer join para reduzir o shuffle; cada coluna e linha removidas são bytes de shuffle economizados.
  • Duas tabelas grandes → aceite o sort-merge join, mas verifique primeiro se há skew (Etapa 5).

Etapa 5: Diagnosticar e corrigir skew

Sintomas de skew: o estágio está quase completo, exceto por uma ou duas tarefas; a duração máxima da tarefa excede ~3-5x a mediana; uma partição de leitura de shuffle é muito maior que as demais na Spark UI. O tratamento de skew-join da AQE divide uma partição quando ela está tanto acima de 5x o tamanho mediano da partição quanto acima de 256 MB (os padrões) — verifique se ele foi ativado no plano. Quando a AQE não puder ajudar (ex.: agregação desbalanceada), faça salting das chaves quentes: adicione um sufixo aleatório 0..N à chave no lado grande, exploda o lado pequeno por todos os N sufixos, faça o join e depois remova o sal. Escolha N ≈ o fator de skew (uma chave 20x maior que a mediana recebe N=20).

Etapa 6: Controlar particionamento e layout de saída

  • repartition(n, col) faz um shuffle completo para balancear dados; use antes de writes amplos.
  • coalesce(n) reduz partições sem shuffle; use para evitar arquivos de saída muito pequenos.
  • Aponte para arquivos de saída de 128 MB-1 GB; milhares de arquivos pequenos penalizam todo leitor downstream.
  • Faça partitioning da saída apenas por colunas de baixa cardinalidade (data, região — dezenas a centenas de valores, nunca IDs):
df.write.partitionBy("dt").mode("overwrite").parquet("/data/out")

Etapa 7: Fazer cache apenas do que for reutilizado

Faça cache apenas quando um DataFrame for usado múltiplas vezes no DAG, materialize-o e limpe o cache quando terminar:

df.cache()
df.count()  # materializar
# ... reutilizar df ...
df.unpersist()

Fazer cache de um DataFrame usado uma vez só desperdiça memória e pode despejar dados que importavam.

Etapa 8: Verificar com o plano

Execute novamente df.explain(True) e confirme que a estratégia pretendida aparece (BroadcastHashJoin, filtros empurrados, sem Exchange onde um foi eliminado). Leia formatos colunares (Parquet, ORC) para que a poda por predicados funcione, nunca use collect() em dados grandes para o driver, e prefira referências F.col em vez de colunas string ao encadear.

Exemplo prático: join ruim vs bom

Ruim — uma tabela de eventos de 2 TB juntada a uma dimensão de 200 MB, largura total, UDF Python para parsing:

result = (events.join(dims, "store_id")          # sort-merge: faz shuffle de todos os 2 TB
    .withColumn("region", parse_region_udf("meta"))  # Python linha a linha
    .filter(F.col("dt") == "2024-06-01"))            # filtra DEPOIS do join

O plano mostra um Exchange em ambos os lados (2 TB shuffled), e a UDF bloqueia a geração de código.

Bom — filtre e projete primeiro, faça broadcast da dimensão, use função embutida:

result = (events
    .filter(F.col("dt") == "2024-06-01")              # poda para ~30 GB primeiro
    .select("store_id", "amount", "meta")
    .join(broadcast(dims.select("store_id", "region_code")), "store_id")
    .withColumn("region", F.regexp_extract("meta", r"region=(\w+)", 1)))

O plano agora mostra BroadcastHashJoin sem Exchange do lado grande: ~30 GB escaneados, zero shuffle da tabela grande, sem fronteira Python.

Resultado

Produza o código revisado do job mais uma nota de ajuste contendo: a estratégia de join para cada join com a evidência de tamanho, a configuração de shuffle-partitions com sua aritmética, qualquer skew encontrado (razão max-vs-median das tarefas) e a correção aplicada, decisões de cache, expectativas de tamanho de arquivo de saída e os deltas do explain antes/depois para uma passagem de ajuste.

NÃO FAÇA

  • NÃO faça broadcast de uma tabela que você não dimensionou — um broadcast mal avaliado causa OOM em todos os executores de uma vez.
  • NÃO escreva uma UDF Python antes de verificar pyspark.sql.functions; quase toda lógica de string, data e condicional tem uma função embutida.
  • NÃO use collect() ou toPandas() em um DataFrame grande; isso canaliza todos os dados do cluster por um único driver.
  • NÃO faça partition da saída por uma coluna de alta cardinalidade — milhões de diretórios, uma linha cada.
  • NÃO jogue executores em um job cujo estágio lento é uma tarefa desbalanceada; mais núcleos não conseguem dividir uma partição.
  • NÃO faça cache por reflexo; faça cache apenas de DataFrames reutilizados downstream, e limpe o cache.

Nível de qualidade

Um job finalizado só é aprovado quando: cada join nomeia sua estratégia e a evidência de tamanho para ela; spark.sql.shuffle.partitions é derivada do tamanho dos dados, não deixada em um valor de hábito; a Spark UI não mostra nenhuma tarefa acima de ~3x a duração mediana em estágios de shuffle (ou o skew é explicado e corrigido); nenhuma UDF Python escalar sobrevive onde existe função embutida; os arquivos de saída se enquadram na faixa de 128 MB-1 GB; e o explain final confirma o plano pretendido.

Individual skills in this repo

This repo contains 19 individual skills — each has its own dedicated page.

SkillMedev/skills

Designs REST API surfaces - resource naming, HTTP method and status-code semantics, error shapes, pagination, and filtering - and delivers an endpoint spec a consumer can build against without asking questions. Use when someone asks "how should I name this endpoint", "what status code should this return", "should this be PUT or PATCH", "how do I paginate this list", or is reviewing an API before it ships to external consumers. Do NOT use for planning breaking-change rollouts and deprecation windows - use api-versioning-strategist instead; for GraphQL type and resolver design - use graphql-schema instead; for generating client SDKs from an existing spec - use api-client-generator instead; for designing inbound webhook endpoints - use webhook-receiver-hardener instead.

SkillMedev/skills

Produce an accurate, properly timed caption track (SRT or WebVTT) from a video's audio - transcribing or aligning to the voiceover script, timing cues to speech, and enforcing line-length and reading-speed rules so captions are readable and in sync. Use when someone says "generate captions", "make subtitles from the audio", "transcribe and caption this", "export an SRT or VTT", "the captions are out of sync", or "the subtitles flash by too fast to read". Do NOT use to burn-in, style, reframe, or position an existing caption track for a platform (9:16, brand styling, safe areas) - that is social-video-formatter; do NOT use to animate text word-by-word as a motion graphic - that is kinetic-typography; do NOT use to write the spoken script in the first place - that is narration-script.

SkillMedev/skills

Turns data and charts into a decision-driving narrative structured as headline finding, trend, implication, and recommended action - with finding-led chart titles, context for every number, annotation guidance, and honest flags on any conclusion the data cannot support. Use when someone says "turn these numbers into a story", "what's the takeaway from this data", "help me present these results to leadership", or has charts but no narrative. Do NOT use for compressing a long document into a one-pager - use executive-summary instead - or for running the analysis that produces the findings - use eda-playbook instead.

SkillMedev/skills

Use when a task needs live or historical money data - "convert USD to EUR", "current/past exchange rate", "FX rate on this date / over this range", or "current price of Bitcoin/Ethereum, market cap, 24h change". Frankfurter (ECB reference rates, no key) is the FX default; CoinGecko's free keyless tier covers crypto. Do NOT use for stock quotes or equities - no keyless stock API survives verification, say so instead of guessing; do NOT use for country economic indicators like GDP or inflation series - use government-open-data instead; if the request is a vague "I need live data", route through public-data-api-picker.

SkillMedev/skills

Builds a driver-based FP&A operating model linking business inputs to P&L, balance sheet, and cash flow outputs. Use when building an annual plan, preparing investor materials, running scenario analysis, or stress-testing the business.

SkillMedev/skills

Use when a task needs live geographic lookups - "geocode this address", "what's at these coordinates" (reverse geocoding), "lat/lon for this city", "which country/state is this ZIP or postal code in", or "country facts: capital, currency, population, flag". Nominatim (OpenStreetMap) is the geocoding default; Zippopotam for postal codes; APICountries for country facts. All keyless. Do NOT use for weather at a location - use weather-climate instead; do NOT use for country-level statistics over time (GDP, population trends) - use government-open-data instead; if the request is a vague "I need live data", route through public-data-api-picker.

SkillMedev/skills

Runs the full Getting Things Done loop - capture, clarify, organize, reflect, engage - building a trusted system of context lists, a projects list with defined next actions, and a weekly review habit. Use when someone says "I'm overwhelmed and things are slipping through the cracks", "set up GTD for me", "help me do a brain dump and organize it", or "my to-do list is a mess". Do NOT use for just running the weekly review ritual itself - use weekly-review instead - or for clearing an email backlog - use inbox-zero.

SkillMedev/skills

Processes any email backlog to zero using the 4Ds - Delete, Delegate, Defer, Do - with a mass-archive strategy for the obvious, a touch-each-email-once discipline, and a keep-it-clear system of batched processing windows, ruthless unsubscribing, filters, and a minimal folder setup. Use when someone says "I have 5,000 unread emails", "help me get to inbox zero", "email is eating my whole day", or treats their inbox as a to-do list. Do NOT use for drafting the reply emails themselves or prioritization rules for an ongoing support queue - use email-triage instead - or for protecting focus time around the email windows - use deep-work-planner instead.

SkillMedev/skills

Write landing-page copy section by section - hero, social proof, features-as-benefits, objections, CTA - leading with one promise and proving it down the page. Use when someone asks "write my landing page", "improve my hero headline", "what should the homepage say", "turn these features into benefits", or is shipping a new page for a launch or campaign. Do NOT use for testing and optimizing an existing page's conversion rate - use landing-page-cro instead; for the one-line claim itself use positioning-statement; for the full message ladder use messaging-hierarchy.

SkillMedev/skills

Improves an existing landing page's conversion rate through evidence-first CRO - audit heatmaps and recordings, write structured hypotheses, prioritize with ICE scoring, and run one-variable tests to statistical significance. Use when someone asks "why isn't my landing page converting", "audit this page before we scale spend", "which A/B test should we run first", or after a CVR drop or ahead of a paid-traffic push. Do NOT use for writing a new landing page from scratch - use landing-page-copy instead. Do NOT use for auditing the ad accounts sending the traffic - use paid-acquisition-audit instead. Do NOT use for reading the results of a finished experiment - use ab-test-analyzer instead.

SkillMedev/skills

Runs structured coaching sessions using values clarification and the GROW model, ending every session with one committed action, a deadline, and an if-then plan for the likely obstacle. Use when someone says "I feel stuck in my life", "help me figure out what I want", "hold me accountable to my goals", or "coach me through this decision". Do NOT use for building a stress toolkit - use stress-management instead - or a journaling practice - use journal-framework; for a standing goal-tracking system, use goals-accountability. Coaching, not therapy: signs of clinical distress route to a licensed professional.

SkillMedev/skills

Adapts English content for a target language and region - swapping idioms, setting the right formality register, replacing cultural references, converting dates, units, and currency - and delivers the localized text with a notes column explaining each adaptation and flagging what needs a native reviewer. Use when someone asks "localize this copy for the Japanese market", "adapt our marketing copy for the Mexican market", "make this translation sound native instead of literal", or a literal translation reads foreign, stiff, or risky. Do NOT use for auditing in-product UI text quality - use ux-writing-audit instead.

SkillMedev/skills

Turns a natural-language video brief into a complete, ready-to-preview Remotion composition - extracts duration, scenes, brand colors, aspect ratio, and real copy; plans the frame budget; and writes data-driven React/TypeScript using useCurrentFrame, interpolate, spring, AbsoluteFill, and Sequence, registered in Root.tsx. Use when someone says "build a 20-second product demo video", "animate a feature walkthrough", "write the Remotion code for this marketing clip", or wants a scene-by-scene composition they can scrub in Studio. Do NOT use for rendering, iterating, or batching the finished MP4 - use remotion-render instead - or for installing and scaffolding the project - use remotion-setup instead.

SkillMedev/skills

Scaffolds a new Remotion video project wired for Claude Code Agent Skills - Node check, create-video scaffold, skills install, folder conventions, Google Fonts, and a smoke-test render. Use whenever someone wants to start making videos with Remotion and Claude, even just "make product videos with Claude.

SkillMedev/skills

Classifies incident severity (SEV1-4) using impact, scope, and urgency signals and decides who to page. Use when an alert fires or a report comes in and a severity call must be made quickly.

SkillMedev/skills

Use the Skill Me catalog from inside any conversation - discover, install, and manage Claude skills through the Skill Me MCP, and load installed skills automatically each session.

SkillMedev/skills

Write one platform-native caption from a topic and brand voice, with a front-loaded hook, native length, and a single earned CTA. Use when the user gives a topic (and optionally brand voice or a described image/video) and asks for an Instagram, LinkedIn, X/Twitter, or TikTok caption. Do NOT use when the user wants a dedicated standalone LinkedIn post - use linkedin-post-writer instead; or a multi-post X thread - use tweet-thread-builder instead; or to adapt one existing piece of content into versions for several channels - use cross-platform-reformatter instead.

SkillMedev/skills

Reframe and export a finished video for social platforms - 9:16 ↔ 16:9 cropping, burned-in captions, a platform-native first frame, loop design, and per-platform specs (aspect, length, safe areas) for TikTok, Reels, Shorts, X, and LinkedIn. Use when someone says "make this vertical", "crop to 9:16", "format for TikTok/Reels/Shorts", "add captions/subtitles", "why is my video cut off on mobile", "resize for Instagram", or "export for social". Do NOT use when the question is about the storyboard or shot order before any video exists (use video-storyboard); the animation craft of how elements move (use motion-design-principles); animated word-by-word caption styling (use kinetic-typography); palette, contrast, or lighting (use motion-color-and-light); directing the product-demo content and screen choreography (use product-demo-director); or scoring, beat-syncing, or audio (use sound-and-music-sync) - this is the craft layer that decides WHAT to format for the feed, then hands a concrete spec to remotion-compo...

SkillMedev/skills

Builds clean, performant, accessible SwiftUI views with correct state ownership, scoped invalidation, and smooth list scrolling, and reviews existing SwiftUI code against a concrete frame-time and re-render budget. Use when someone asks "why does my SwiftUI list stutter", "should this be @State or @Observable", "my whole screen re-renders when one row changes", "how do I animate this transition", or wants a SwiftUI view built or refactored. Do NOT use for cross-platform React Native apps - use react-native-pro instead; do NOT use for Flutter widget trees - use flutter-widget-architect instead; do NOT use for Android Compose UIs - use jetpack-compose-builder instead.

Habilidades Relacionadas