BeginnerSpark · 13 min · 2 challenges

Catalyst Optimizer: Beginner

Hand the same Spark query to a beginner and to an expert and it often runs in the same time, because Catalyst rewrites both before they execute. In older Spark you hand-tuned everything with RDDs, where a clumsy ordering cost you dearly. DataFrames changed the deal: you declare what you want, and Spark works out how to get it, the same bargain SQL has always offered. You already write SQL trusting the planner to find the cheap path. This tier shows you the engine that earns that trust for Spark, starting from one shift: you stopped telling Spark how and started telling it what.

DataFrames over RDDs

Daily Life

Interviews

Spark has two ways to express a computation, and they split along command versus request. The older way is the RDD, a Resilient Distributed Dataset, where you write the actual steps: map this function over the data, then filter with that one, then reduce in this particular order. You hand Spark a procedure, and Spark runs it more or less as you wrote it. An inefficient ordering stays inefficient, because all Spark sees is a sequence of opaque functions it must execute faithfully.

The newer way is the DataFrame, where you describe the result you want in terms of named columns and relational operations: select these columns, where this condition holds, grouped by that key. You hand Spark a description, and Spark understands every part of it. It knows what a filter is, what a groupBy means, what columns each step needs. Because it understands the operations instead of running opaque functions, it can reason about them and rearrange them for efficiency. SQL has always offered the same bargain: you write what you want, the engine decides how.

⚠RDD (you say HOW)

You write the exact procedure
Spark runs your steps as given
Opaque functions Spark cannot inspect
No optimization; your ordering is final

•DataFrame (you say WHAT)

You describe the result you want
Spark chooses how to compute it
Relational ops Spark understands
Catalyst rewrites it for efficiency

This consequence is why DataFrames are the default for almost everything today. Two engineers can write the same DataFrame query in different orders, with the filter early or late, with the columns selected before or after a join, and Catalyst rewrites both into the same efficient plan. The optimizer absorbs the difference between a clumsy expression and a clean one. RDDs gave you no such safety net: the clumsy version ran clumsily. DataFrames moved the burden of optimization from you to Spark.

The seed tables make this concrete. Suppose you want total revenue per category for in-stock products, and you join order_items to products and then filter on in_stock. An RDD version joins every order_items row to every product first, building a large intermediate, and only then drops the out-of-stock rows, because you wrote the steps in that order and the RDD runs them in that order. The DataFrame version expresses the same intent, and Catalyst can apply the in_stock filter to products before the join, so the join touches fewer product rows. Same result, far less intermediate data, no thought required from you. Commanding the steps and describing the goal pull apart right here.

If you have written SQL, you already trust this bargain without naming it. You would never expect a database to scan a billion-row orders table just because you wrote WHERE customer_id = 42 at the end of the query; you trust the planner to use an index or push the predicate into the scan. DataFrames bring that same trust to Spark. Writing RDDs meant writing the storage engine's access path by hand every time, which is why a clumsy RDD ordering was so punishing and why almost nobody starts a new pipeline that way anymore.

The same intent, optimized for you

The demo below is an ordinary DataFrame query: a filter, a grouping, an aggregation. You wrote what you want, a count of in-stock products per category, and Spark decides how to run it, including pushing the filter as early as possible. Run it and hold onto one fact: you did not specify an execution order, you specified a result.

(products
   .filter(F.col("in_stock") == 1)
   .groupBy("category")
   .agg(F.count(F.lit(1)).alias("n"))
   .orderBy(F.col("n").desc(), F.col("category").asc()))

Nothing in that query told Spark when to apply the filter relative to the scan, or how to organise the aggregation. You expressed intent, and the optimizer filled in the how. Splitting intent from execution is what makes Spark feel like SQL even when you write Python or Scala. The rest of the beginner tier covers what the optimizer actually does with the intent you give it.

Notice the other things you did not write: how many partitions to use for the grouping, which executor should hold which category, whether the count should be computed partially on each node and combined at the end. Those are all real decisions, and Spark makes every one of them from the relational shape of the query. A groupBy followed by a count is a pattern Spark recognises, so it computes partial counts locally and ships only the small partials across the network to be summed. With an RDD and a manual reduce you would have had to choose that two-phase pattern yourself, and getting it wrong means shuffling every raw row.

TIP

When an interviewer asks why DataFrames are preferred over RDDs, answer in one sentence: the DataFrame API is declarative, so Spark understands your operations and can optimize them, whereas an RDD is imperative and opaque, so Spark must run your steps as written. Pushdown, codegen, and join strategy all follow from that one distinction between describing a result and dictating a procedure.

Your Query Gets Rewritten

Daily Life

Interviews

Between the moment you describe a DataFrame and the moment it runs, Catalyst rewrites it. These are not minor cleanups but a series of transformations that can change your query substantially while guaranteeing the same result. Start with the two simplest and most impactful rewrites: constant folding and filter pushdown.

Constant folding is the easy one. If your query contains an expression that can be computed without looking at the data, like a comparison against two plus three, Catalyst computes it once at planning time and substitutes the result, rather than recomputing two plus three for every one of a billion rows. It is the same optimization a compiler does, applied to your query. You will rarely write something this obviously constant, but generated queries and templated logic produce these all the time, and the optimizer quietly collapses them.

Filter pushdown is the one that matters for performance. If you filter late in your query, Catalyst moves the filter as early as it can, ideally all the way down to the data source, so fewer rows enter every subsequent step. A filter you wrote after a join can get pushed to before the join, so the join works on less data. A filter on a column the file format can skip on can get pushed into the read itself, so rows that fail it are never loaded. You wrote the filter where it read clearly; Catalyst runs it where it costs least.

Column pruning is the third rewrite you meet constantly, and it is the quiet companion to filter pushdown. If you read the products table but your query only ever references category and price, Catalyst prunes the read down to those two columns and never loads the rest. On a columnar format like Parquet this is enormous: the file format can skip entire column chunks on disk, so a table with 40 columns is read as if it had two. You wrote select category, avg(price) without thinking about the other 38 columns; the optimizer noticed they are never used and stopped reading them. Filter pushdown drops rows you do not need, column pruning drops columns you do not need, and together they shrink the read in both dimensions.

same result, less work

the optimizer's promise

Carry this model: your DataFrame code describes intent, and Catalyst can achieve that intent any way that produces the identical result. It reorders, collapses, and relocates your operations without asking, because it can prove the result is unchanged. That is liberating once you trust it. You write your query in the order that reads most clearly to a human, and the optimizer worries about the order that runs fastest on a machine. The clarity you write and the efficiency you get come apart.

One honest caveat belongs here, because the advanced tier returns to it: the optimizer is only as good as what it knows. It makes many decisions from estimates about how big things are, and when those estimates are wrong, it can choose poorly. For ordinary queries on well-described data, Catalyst is excellent and you can largely forget it is there. For unusual queries or stale statistics, knowing that the optimizer guessed is the first step to fixing a plan that went wrong.

Be precise about what same result means, because that guarantee is why you can trust the rewrites. Catalyst applies a transformation only when it is provably equivalent on every possible input, not merely on the data you happen to have. Pushing a filter below a join is legal because the rows that survive the filter are the same rows that would have survived it after the join; the optimizer can prove that, so it does it without asking. A SQL query rewriter holds itself to the same standard, and that is why you never have to verify the rewritten query: correctness is a precondition of the rewrite, not something you check afterward.

One practical habit follows from all this. Because the order you write operations in does not change the result and rarely changes the speed, you should write for the next human to read, not for the machine. Put the filter where it makes the intent clearest, name your intermediate columns, and let the layout follow the logic of the problem. The engineer who contorts a query into what they imagine is an efficient order is usually fighting a battle Catalyst already won, and producing less readable code for no runtime benefit. Clarity for you and efficiency from the optimizer is the deal DataFrames offer, and you should take it.

The RDD Escape Hatch

Daily Life

Interviews

Spark still lets you drop down to RDDs whenever you want, and occasionally you genuinely need to, for a transformation the DataFrame API cannot express. Understand what you give up when you do, because the cost stays invisible until you measure it: the moment you convert a DataFrame to an RDD and apply your own function, the optimizer goes blind.

Catalyst can optimize DataFrames because it understands the relational operations. An RDD transformation is an arbitrary function, a black box that takes a row and returns something. Catalyst cannot see inside it, cannot tell whether it filters or transforms or which columns it touches, and so cannot reason about it. Once your data flows through an opaque RDD function, the optimizer can no longer push filters across it, prune columns through it, or fuse it with neighbouring operations. Optimization stops at the black box.

•Staying in DataFrames

Operations are transparent to Catalyst
Filters push down, columns prune
Tungsten generates fast fused code
The optimizer works for you

⚠Dropping to an RDD function

Your function is opaque to Catalyst
The optimizer cannot see through it
No pushdown, no pruning across it
Steps run as written, unoptimized

Here is the cost with a concrete shape. Say you want orders enriched with a derived flag, and you write it as an RDD map that takes each order row, computes the flag, and returns a new row, then later you filter on customer_id and select 3 columns. To Catalyst the map is opaque, so it cannot know the downstream filter only needs customer_id, and it cannot push that filter below the map or prune the unused columns through it. Every order row flows through your function in full, even the ones the filter will immediately discard and the columns nobody reads. The same logic in the DataFrame API, a withColumn for the flag, stays transparent, and Catalyst pushes the filter to the scan and prunes the columns, so the expensive per-row work runs on a fraction of the data.

The guidance follows directly: stay in the DataFrame API unless you have a specific reason not to. Almost everything you might reach for an RDD to do, custom aggregations, complex conditional logic, working with nested data, can be expressed with DataFrame functions, SQL expressions, or built-in higher-order functions, all of which Catalyst understands. Reaching for an RDD should be a deliberate, rare decision made because you truly cannot express something otherwise, never a reflex.

TIP

A common interview signal: a candidate who reaches for RDDs on a problem the DataFrame API handles is showing they learned Spark a version or two ago. The senior instinct runs the other way: stay declarative so the optimizer keeps working, and treat dropping to an RDD as a cost to justify, not a tool to prefer.

User-defined functions deserve the same caution, for the same reason. To Catalyst a Python UDF is another opaque function, and it carries an extra penalty the advanced lesson on serialization covers: each row has to cross from the JVM to Python and back. The pattern holds throughout: every time you hand Spark an opaque function instead of a relational operation it understands, you turn off a piece of the optimizer, so do it only when the expressiveness earns the blindness.

Before you write any UDF, run through a short checklist, because the built-in library is wider than most people remember. Conditional logic goes in when and otherwise. String work has dozens of functions from regexp_extract to split. Dates have their own family. Nested arrays and structs have transform, filter, and aggregate higher-order functions that run inside the engine. JSON has from_json and get_json_object. Only when none of these can express what you need, which is genuinely rare for the kind of work the seed tables represent, does a UDF become the right tool. Treating the UDF as the last resort rather than the first instinct keeps the optimizer and the engine working on your behalf.

DataFrame, Dataset, and RDD

Daily Life

Interviews

Spark exposes three APIs for distributed data, and they sit on a spectrum from most optimized to most flexible. Knowing where each sits, and what it trades, lets you choose deliberately instead of by habit. The three are the RDD, the DataFrame, and the Dataset, and the axis that separates them is how much Spark understands about your data and operations.

API	What Spark knows	What you get / give up
RDD	Nothing; opaque functions on opaque objects	Maximum control, zero optimization
DataFrame	Named columns and relational ops	Full Catalyst + Tungsten, untyped rows
Dataset	Columns AND your object types (JVM)	Optimization plus compile-time type safety

The RDD knows nothing: it is a distributed collection of arbitrary objects, and Spark runs whatever functions you give it without understanding them. You get total control and no optimization, which today is rarely the trade you want. The DataFrame knows your data as named columns with types and your operations as relational steps, which is what Catalyst needs, so you get the full optimizer and the fast Tungsten engine. The cost is that a DataFrame row is untyped from the language's view; a wrong column name is caught at runtime, not when you compile.

The Dataset, available in Scala and Java, aims for both. It is a DataFrame that also knows your JVM object type, so you get Catalyst optimization AND compile-time type safety: a wrong field name fails to compile rather than failing at runtime. The catch is that operating on typed objects sometimes forces Spark to deserialize rows into your objects, which can cost some of the Tungsten efficiency the pure DataFrame keeps. In Python there is no Dataset, because Python has no compile-time types to offer, so the DataFrame is the typed-enough default.

The untyped cost of a DataFrame is easy to feel in practice. Write products.select("catagory") with the column misspelled, and nothing complains until Spark analyzes the plan and throws at runtime, possibly minutes into a job. In a Scala Dataset of a Product case class, the same typo is product.map(_.catagory), which does not compile, so you learn about it in your editor before the job ever starts. That earlier feedback is what you buy with a Dataset, and on a long, multi-step pipeline where a runtime failure is expensive to reproduce, the compile-time check can be worth the small engine overhead the typed object access costs.

For day-to-day work the answer is almost always the DataFrame, or its SQL equivalent, which compiles to the same plan. It gives you the optimizer and the engine, it works identically across Python, Scala, and SQL, and the lack of compile-time column checking is a manageable cost in exchange for the performance. Reach for a Dataset in Scala when type safety on a complex pipeline is worth a little engine overhead, and reach for an RDD only when you genuinely cannot express something any other way.

Seeing It with explain()

Daily Life

Interviews

You do not have to take the optimizer on faith; you can watch it work. The explain method prints the plan Spark intends to run, and comparing it to the query you wrote shows what Catalyst changed. The clearest thing to look for is a filter you wrote showing up in the plan pushed down to the scan, proof that the optimizer moved your work to where it costs least.

You read a plan from the bottom up, because that is the order data flows: the leaves are the scans that read your tables, and each operator above consumes the one below it. So the bottom of the plan tells you what gets read, and what got pushed into the read. When your filter shows up as a PushedFilters entry at the scan, Catalyst pushed it down and you are reading fewer rows. When it shows up as a separate Filter operator higher up, it did not push down, and that is worth asking why.

In the plan	What it tells you	Why it matters
PushedFilters at the scan	Your filter runs at the data source	Fewer rows are ever read; this is the win
A separate Filter operator	The filter did not push down	Investigate; you may be reading too much
Project with fewer columns	Column pruning happened	Only needed columns are carried
Exchange	A shuffle Catalyst planned	The wide operations, where cost concentrates

Reading explain turns the optimizer into something you can verify. Before a big job you can call explain without running anything, because the plan is built lazily, and check that your filters pushed down and no unexpected shuffle appeared. After a job disappoints, the plan tells you what Spark actually did versus what you assumed. Either way, the habit of reading plans separates an engineer who hopes the optimizer helped from one who confirms it did.

There is more than one explain to know. The plain explain prints the final physical plan, which is what you usually want, but explain(True) prints all four stages: the parsed plan, the analyzed plan, the optimized logical plan, and the physical plan, one after another. Reading them in sequence is the clearest way to see Catalyst at work, because you can watch a filter that sat near the top of the parsed plan migrate down toward the scan in the optimized plan. When you are learning what the optimizer does, explain(True) on a small query and a careful read of the before and after will teach you more than any description can, this one included.

Confirm the pushdown yourself

The query below filters then aggregates. Run it, then call explain on it in your head: the filter on category would appear pushed down toward the scan, so the aggregation works on fewer rows. Complete the filter that the optimizer will relocate and the aggregation it feeds.

> From order_items, keep only rows with quantity above 1, then return total revenue (quantity times unit_price) per product_id, highest first. Catalyst will push the filter toward the scan so the aggregation sees fewer rows.

(order_items
   .___(F.col("quantity") > 1)
   .groupBy("product_id")
   .agg(F.___(F.col("quantity") * F.col("unit_price")).alias("revenue"))
   .orderBy(F.col("revenue").desc()))

filter

sum

groupBy

select

You wrote the filter and the aggregation in a readable order; Catalyst runs the filter first so the expensive aggregation touches less data. Declare the result, let the optimizer find the cheap path, and use explain to confirm it did. The intermediate tier opens up the phases Catalyst goes through to produce that plan.

One caution about pushdown that the plan will teach you: not every filter can be pushed to the source, and the plan is honest about which ones were. A filter on a plain column of a Parquet table pushes down cleanly and shows up as a PushedFilters entry at the scan. A filter that wraps the column in a function the source cannot evaluate, or one that depends on a computed column, stays as a separate Filter operator above the scan, because the source has no way to apply it. Seeing the difference in the plan tells you when a small rewrite, filtering on the raw column instead of a transformed one, would let the pushdown happen and cut the read.

✓Do

Stay in the DataFrame or SQL API so Catalyst can optimize your query.
Write queries in the order that reads clearly; let the optimizer reorder for speed.
Call explain before a big job to confirm filters pushed down and no surprise shuffle appeared.
Prefer built-in functions and SQL expressions over opaque UDFs and RDD functions.

✗Don't

Don't drop to an RDD for something the DataFrame API can express; you blind the optimizer.
Don't assume a filter pushed down; read the plan and confirm PushedFilters at the scan.
Don't reach for a UDF reflexively; it is a black box Catalyst cannot see through.
Don't hand-tune operation order in DataFrames; Catalyst already does it better.

❯❯❯PUTTING IT ALL TOGETHER

> You inherit a Spark job written mostly with RDD map and filter functions that runs slower than a colleague expects for its data size. You are asked to make it faster without changing what it computes.

The RDD functions are opaque to Catalyst, so the optimizer cannot push filters down or prune columns across them.

You rewrite the logic in the DataFrame API, expressing the same filters and aggregations as relational operations.

Now Catalyst can rewrite the query: it pushes the filters to the scan and prunes the columns the job never uses.

You call explain to confirm the filters show up as PushedFilters at the scan, proving the optimizer is now doing the work the RDD version blocked.

KEY TAKEAWAYS

DataFrames let you declare what you want; Catalyst decides how, the way SQL always has.

Catalyst rewrites your query for the same result with less work: constant folding, filter pushdown, column pruning.

Dropping to an RDD or a UDF hands Catalyst an opaque function and turns off optimization across it.

RDD, DataFrame, and Dataset trade control for optimization; the DataFrame is the default for almost everything.

explain() shows the plan Catalyst built, so you can confirm pushdown and pruning instead of hoping.

You stopped telling Spark how, and started telling it what.

Category: Spark
Difficulty: beginner
Duration: 13 minutes
Challenges: 2 hands-on challenges

Topics covered: DataFrames over RDDs, Your Query Gets Rewritten, The RDD Escape Hatch, DataFrame, Dataset, and RDD, Seeing It with explain()

Lesson Sections

DataFrames over RDDs (concepts: sparkDataFrameBasics)
Spark has two ways to express a computation, and they split along command versus request. The older way is the RDD, a Resilient Distributed Dataset, where you write the actual steps: map this function over the data, then filter with that one, then reduce in this particular order. You hand Spark a procedure, and Spark runs it more or less as you wrote it. An inefficient ordering stays inefficient, because all Spark sees is a sequence of opaque functions it must execute faithfully. The newer way i
Your Query Gets Rewritten (concepts: paCatalystOptimizer)
Between the moment you describe a DataFrame and the moment it runs, Catalyst rewrites it. These are not minor cleanups but a series of transformations that can change your query substantially while guaranteeing the same result. Start with the two simplest and most impactful rewrites: constant folding and filter pushdown. Constant folding is the easy one. If your query contains an expression that can be computed without looking at the data, like a comparison against two plus three, Catalyst compu
The RDD Escape Hatch (concepts: sparkRddApi)
Spark still lets you drop down to RDDs whenever you want, and occasionally you genuinely need to, for a transformation the DataFrame API cannot express. Understand what you give up when you do, because the cost stays invisible until you measure it: the moment you convert a DataFrame to an RDD and apply your own function, the optimizer goes blind. Catalyst can optimize DataFrames because it understands the relational operations. An RDD transformation is an arbitrary function, a black box that tak
DataFrame, Dataset, and RDD (concepts: sparkRddApi)
Spark exposes three APIs for distributed data, and they sit on a spectrum from most optimized to most flexible. Knowing where each sits, and what it trades, lets you choose deliberately instead of by habit. The three are the RDD, the DataFrame, and the Dataset, and the axis that separates them is how much Spark understands about your data and operations. The RDD knows nothing: it is a distributed collection of arbitrary objects, and Spark runs whatever functions you give it without understanding
Seeing It with explain() (concepts: paCatalystOptimizer)
You do not have to take the optimizer on faith; you can watch it work. The explain method prints the plan Spark intends to run, and comparing it to the query you wrote shows what Catalyst changed. The clearest thing to look for is a filter you wrote showing up in the plan pushed down to the scan, proof that the optimizer moved your work to where it costs least. You read a plan from the bottom up, because that is the order data flows: the leaves are the scans that read your tables, and each opera