mongo-spark and what the official connector does and does not settle

A vendor connector, which changes who owns the bugs

mongo-spark is described in one line as the official MongoDB Spark Connector, and the primary language of the repository is Java. That word official is the whole point of the project and it has practical consequences for anyone deciding whether to depend on it.

The connector lives in the mongodb organisation rather than in a community namespace, the licence is Apache-2.0, and the documentation and API documentation are hosted on MongoDB's own domains, with the user guide at docs.mongodb.com/spark-connector/ and the API reference published through javadoc.io for the org.mongodb.spark.mongo-spark-connector artifact.

The build instructions are marked as intended for internal use, and the project guide redirects anyone who wants to use the connector to the downloading section instead. That is a deliberate line: the repository documents how MongoDB builds the connector, and the documentation site documents how you use it.

For an engineer, the significance is who gets the bug fixed. A connector maintained by the database vendor means an issue raised against it is routed to people who also maintain the server and the drivers, which is a different guarantee from a community port that depends on upstream behaviour changes.

The repository is a Gradle project, with build.gradle.kts and settings.gradle.kts, a gradle.properties file, wrapper scripts for both Unix and Windows, and a config/ directory alongside src/.

The support text in this repository is about the wrong connector

There is a mistake in the support section of the project guide, and it is worth pointing out because anyone following it literally will end up in the wrong place.

The section headed Support / Feedback tells the reader that for issues with, questions about, or feedback for the MongoDB Kafka Connector, they should look into MongoDB's support channels, and it warns not to email any of the Kafka connector developers directly with issues or questions, pointing instead to the MongoDB Community Forums, in the drivers and ODMS connectors section for the Spark connector.

Every mention of Kafka in that paragraph is a copy and paste from the sibling connector's guide. The forum tag it points at is the Spark connector one, so the destination is right, but the product named in the text is wrong twice over.

This is a small thing, and it is the kind of small thing that is genuinely useful to know before you assume a page about a project has been reviewed. It also hints at the shape of the surrounding organisation, since there is a separate MongoDB Kafka Connector project with its own guide, its own developers and its own issue handling, and this repository is maintained by people who work alongside it.

For the record, the project has no GitHub releases, so the version you depend on is whatever Maven Central resolves.

Issues live in a public JIRA project, and that is a deliberate choice

The issue handling is unusual enough to describe precisely, because it differs from the default expectation for a GitHub repository.

The project guide asks you to open a case in MongoDB's issue management tool, JIRA, rather than in GitHub Issues. The steps are spelled out: create an account and log in at jira.mongodb.org, go to the SPARK project, and click Create Issue, with as much information as possible about the issue type and how to reproduce it.

Two things follow from that. The first is that a report is public, which the guide states directly, so anything you paste into a JIRA issue is visible to the world. The second is that you need a MongoDB JIRA account before you can report anything, which is one more step than opening a GitHub issue and one more place for a report to end up.

The guide also sets out what a good report contains. At a minimum you should include the exact version of the driver you are using. If you are having connectivity issues it is often useful to paste in the connector configuration, and you should check your application logs for connectivity-related exceptions and post those as well.

That last instruction is the most telling. The connector is a bridge between two systems that fail independently, and the guide is telling reporters to hand over evidence from both sides rather than a description of the symptom.

Building it yourself is a Gradle wrapper and one command

The build section is short, and it is explicitly framed as internal, but the commands are the ones you need if you intend to work on the connector rather than consume it.

$ git clone https://github.com/mongodb/mongo-spark.git
$ cd mongo-spark
$ ./gradlew clean check

Three things are worth noticing. The clone URL uses the lower case mongodb organisation path, and the repository default branch is main. The build is driven by the Gradle wrapper checked into the tree, with gradlew and gradlew.bat both present, so the Gradle version used by the build is fixed by the wrapper rather than by whatever is on your machine. And the check task is the one named in the guide, which in a Gradle build is the aggregate verification task, so it is the closest thing here to a single command that says is this tree sound.

The tree also carries an .editorconfig file and a .git-blame-ignore-revs file, the second being the standard way to keep formatting-only commits out of the blame view, and an .evergreen/ directory. Evergreen is MongoDB's own continuous integration system, so the CI configuration for this project lives there rather than in a .github/workflows directory, even though a .github/ directory is also present for the repository-level GitHub metadata.

The build dependencies are pinned in gradle.properties and the module structure is described by settings.gradle.kts, which is where the multi-module layout of src/ is defined.

Dependencies come from Maven Central, and the version information lives there too

The downloading section is where the project tells you where the artefact actually is, and it is worth reading as a statement about who maintains the dependency graph.

The binaries and dependency information for Maven, SBT, Ivy and others can be found on Maven Central, under the group id org.mongodb.spark, with the search page linked from the guide. The coordinates implied by the javadoc link are consistent with that: org.mongodb.spark.mongo-spark-connector.

Publishing to Maven Central means the connector is resolvable by every Java build tool without a custom repository configuration, and it means the transitive dependency set is declared rather than hand-assembled. For a Spark connector this matters, because Spark jobs routinely fail on a missing or conflicting jar in the classpath rather than on anything to do with the connector logic.

It also means the version you use is the version on Maven Central, and the guide points at the search interface rather than at a pinned coordinate or a table of supported versions. There is no compatibility matrix in the repository. The combination of MongoDB server version, Spark version, Scala version and connector version is documented on the connector documentation site instead, which is a reasonable place for a matrix that changes with every Spark release, but it does mean the repository alone cannot answer the first question a new user asks.

Security issues have a separate route, following MongoDB's published vulnerability reporting instructions rather than the JIRA path.

The connector and the Kafka connector are different approaches to the same data

The project guide names a sibling project several times by mistake, and that accident is an opportunity to be clear about the difference in approach between them.

The Spark connector reads from MongoDB. Spark is the query engine, MongoDB is the source, and a job pulls data out of collections for transformation. The connector plugs into the existing Spark data source API, so the connector configuration and the Spark job configuration are two separate things, and the usual shape is a Spark job reading from MongoDB through the connector while Spark handles the rest of the pipeline.

The Kafka connector is the opposite direction and a different mechanism. Kafka is a log, MongoDB is the sink, and data flows in as events rather than being queried out of collections. A Kafka connector also has to solve ordering, replay and exactly-once semantics that a batch read does not.

The difference in approach is worth internalising because people often reach for the Kafka connector when they want change data capture and reach for the Spark connector when they want to query existing collections. The first gives you a stream of events, the second gives you a batch over data that already exists.

For a team deciding between them, the deciding question is whether the requirement is incremental change capture or analytical access to current and historical collections. The connector in this repository answers the second question, and it does so as a library that runs inside a Spark job rather than as a service you deploy.

What the repository does not tell you

Reading this project honestly means acknowledging what is missing, and there are a few gaps that matter to anyone evaluating it.

There is no supported version matrix in the repository. You will not find a table telling you which connector version works with which Spark version or which MongoDB deployment, and the project guide does not point at one either. That information has to come from the documentation site.

There are no GitHub releases, so there is no tag to cite in a design document and no release notes to read. The only versioned artefacts are the ones on Maven Central.

There is no example application. The repository contains the connector, its build files and its CI configuration, and the usage examples live in the documentation rather than in a runnable sample you can clone. For a library, that means the fastest path to a working integration is a documentation page, not a repository.

And the build section says so itself, marking its instructions as intended for internal use. This repository is the source of the connector, not the front door to using it.

Given all of that, the sensible evaluation order is straightforward: read the connector documentation first, check the driver version requirement it states, pull the artefact from Maven Central, and only then decide whether you need to look inside the source at all.

Editorial conclusion

mongo-spark suits a team running Spark jobs against MongoDB that wants a connector maintained by the database vendor rather than a community port, and that needs its dependencies resolved from Maven Central with the version information MongoDB publishes. It does not suit a team that wants to find the connector's supported Spark and MongoDB version matrix inside the repository, because that documentation lives on the MongoDB docs site, and it does not suit anyone who needs a release tag per version, since the project publishes no GitHub releases. Before adopting it, check the connector documentation for the supported combinations, and note that the last push to the repository was on 2026-08-13 with the build driven by Gradle wrappers checked into the tree.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. mongodb/mongo-spark on GitHub
4. Project website
5. README