Notes talking about the design and implementation of Apache Spark
Alternatives To Sparkinternals
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Spark35,8732,39488217 hours ago46May 09, 2021262apache-2.0Scala
Apache Spark - A unified analytics engine for large-scale data processing
2 months ago110apache-2.0
The Data Engineering Cookbook
God Of Bigdata7,992
2 months ago2
Zeppelin6,058322318 hours ago2June 21, 2017142apache-2.0Java
Web-based notebook that enables data-driven, interactive data analytics and collaborative documents with SQL, Scala and more.
2 years ago27
Notes talking about the design and implementation of Apache Spark
18 hours ago4May 23, 20221,351apache-2.0Java
Apache Iceberg
Bigdl4,21910a day ago16April 19, 2021744apache-2.0Jupyter Notebook
Fast, distributed, secure AI for Big Data
517 days ago32April 21, 202213apache-2.0Python
TensorFlowOnSpark brings TensorFlow programs to Apache Spark clusters.
Spark Nlp3,270222 days ago90March 05, 202136apache-2.0Scala
State of the Art Natural Language Processing
Koalas3,2281126 months ago47October 19, 2021109apache-2.0Python
Koalas: pandas API on Apache Spark
Alternatives To Sparkinternals
Select To Compare

Alternative Project Comparisons

Spark Internals

Spark Version: 1.0.2 Doc Version:


Weibo/Twitter ID Name Contributions
@JerryLead Lijie Xu Author of the original Chinese version, and English version update
@juhanlol Han JU English version and update (Chapter 0, 1, 3, 4, and 7)
@invkrh Hao Ren English version and update (Chapter 2, 5, and 6)
@AorJoa Bhuridech Sudsee Thai version


This series discuss the design and implementation of Apache Spark, with focuses on its design principles, execution mechanisms, system architecture and performance optimization. In addition, there's some comparisons with Hadoop MapReduce in terms of design and implementation. I'm reluctant to call this document a "code walkthrough", because the goal is not to analyze each piece of code in the project, but to understand the whole system in a systematic way (through analyzing the execution procedure of a Spark job, from its creation to completion).

There're many ways to discuss a computer system. Here, We've chosen a problem-driven approach. Firstly one concrete problem is introduced, then it gets analyzed step by step. We'll start from a typical Spark example job and then discuss all the related important system modules. I believe that this approach is better than diving into each module right from the beginning.

The target audiences of this series are geeks who want to have a deeper understanding of Apache Spark as well as other distributed computing frameworks.

I'll try my best to keep this documentation up to date with Spark since it's a fast evolving project with an active community. The documentation's main version is in sync with Spark's version. The additional number at the end represents the documentation's update version.

For more academic oriented discussion, please check out Matei's PHD thesis and other related papers. You can also have a look at my blog (in Chinese) blog.

I haven't been writing such complete documentation for a while. Last time it was about three years ago when I was studying Andrew Ng's ML course. I was really motivated at that time! This time I've spent 20+ days on this document, from the summer break till now (August 2014). Most of the time is spent on debugging, drawing diagrams and thinking how to put my ideas in the right way. I hope you find this series helpful.


We start from the creation of a Spark job, and then discuss its execution. Finally, we dive into some related system modules and features.

  1. Overview Overview of Apache Spark
  2. Job logical plan Logical plan of a job (data dependency graph)
  3. Job physical plan Physical plan
  4. Shuffle details Shuffle process
  5. Architecture Coordination of system modules in job execution
  6. Cache and Checkpoint Cache and Checkpoint
  7. Broadcast Broadcast feature
  8. Job Scheduling TODO
  9. Fault-tolerance TODO

Other languages

Chinese Version is at markdown/. Thai Version is at markdown/thai

How to read this document

The documentation is written in markdown. The pdf version is also available here.

If you're under Mac OS X, I recommand MacDown with a github theme for reading.

Gitbook (Chinese version)

Thanks @Yourtion for creating the gitbook version.

Online reading



I've created some examples to debug the system during the writing, they are avaible under SparkLearning/src/internals.

Book version (NEW)

We have written a book named "The design principles and implementation of Apache Spark", which talks about the system problems, design principles, and implementation strategies of Apache Spark, and also details the shuffle, fault-tolerant, and memory management mechanisms. Currently, it is written in Chinese.

Book link:

Book cover: book cover

Book preface:


I appreciate the help from the following in providing solutions and ideas for some detailed issues:

  • @Andrew-Xia Participated in the discussion of BlockManager's implemetation's impact on broadcast(rdd).

  • @CrazyJVM Participated in the discussion of BlockManager's implementation.

  • @ Participated in the discussion of BlockManager's implementation.

Thanks to the following for complementing the document:

Weibo ID Chapter Content Revision status
@OopsOutOfMemory Overview Relation between workers and executors and Summary on Spark Executor Driver's Resouce Management (in Chinese) There's not yet a conclusion on this subject since its implementation is still changing, a link to the blog is added

Thanks to the following for finding errors:

Weibo Id Chapter Error/Issue Revision status
@Joshuawangzj Overview When multiple applications are running, multiple Backend process will be created Corrected, but need to be confirmed. No idea on how to control the number of Backend processes
@_cs_cm Overview Latest groupByKey() has removed the mapValues() operation, there's no MapValuesRDD generated Fixed groupByKey() related diagrams and text
@ JobLogicalPlan N:N relation in FullDepedency N:N is a NarrowDependency Modified the description of NarrowDependency into 3 different cases with detaild explaination, clearer than the 2 cases explaination before
@zzl0 Fisrt four chapters Lots of typossuch as "groupByKey has generated the 3 following RDDs"should be 2. Check pull request All fixed
@TEL Cache and Broadcast chapter Lots of typos All fixed
@cloud-fan JobLogicalPlan Some arrows in the Cogroup() diagram should be colored red All fixed
@CrazyJvm Shuffle details Starting from Spark 1.1, the default value for spark.shuffle.file.buffer.kb is 32k, not 100k All fixed

Special thanks to @Andy for his great support.

Special thanks to the rockers (including researchers, developers and users) who participate in the design, implementation and discussion of big data systems.

Popular Spark Projects
Popular Apache Projects
Popular Data Processing Categories

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Apache Spark