docs(mongodb): document inline TLS certificate fields for UI/Docker

blog/2023-03-29-troubleshooting-common-issues-and-solutions-to-mongodb-etl-errors.mdx

@@ -336,48 +336,67 @@ Are you interested in unlocking the full potential of your data without the need
 With features like data ingestion from 150+ sources including MongoDB connectors, data warehousing, data analytics, and data transformation solutions, Datazip can help you make fast, data-driven decisions.
 
 ## FAQs
-### Q1. What are the most common MongoDB ETL errors and how do you diagnose them?
-- **Connection timeout errors** — Check network connectivity, firewall/security group rules blocking port 27017, and MongoDB authentication credentials
-- **Schema validation failures** — Caused by polymorphic fields or missing required fields across documents in the same collection
-- **Data type mismatch errors** — Where the source field type differs from the target column type
-- **Socket timeout (`socketTimeoutMS`) exhaustion during large collection scans** — Occurs when MongoDB takes longer than the configured `socketTimeoutMS` to respond to a query, common during unoptimized aggregate queries or large full-collection reads. Increase `socketTimeoutMS` in your connection settings and ensure queries are properly indexed to avoid full collection scans.
-
-### Q2. How should I set up MongoDB for ETL to minimize pipeline errors?
-Best practices for an ETL-ready MongoDB setup include:
-
-- **Enable Read Preference on secondary nodes** to offload ETL reads from the primary and avoid impacting operational performance
-- **Create indexes on user-defined timestamp fields** (such as an application-managed `updated_at` field) that are used for cursor-based incremental sync — note this is not a built-in MongoDB field and must be maintained by your application
-- **Set `socketTimeoutMS` and `serverSelectionTimeoutMS`** appropriately per operation for long-running collection reads, keeping in mind these are per-operation settings, not session-level configurations in most drivers
-- **Configure oplog retention** to cover at least 24–48 hours of changes to ensure CDC consumers do not fall behind the retention window
-- **Ensure a replica set is configured:** this is a hard requirement for change streams and oplog-based CDC; standalone MongoDB instances do not support these features
-
-### Q3. What causes connection timeout errors in MongoDB ETL pipelines and how do I fix them?
-Connection timeouts typically occur due to:
-
-- **Network/firewall issues:** Firewall or security group rules blocking the ETL tool's IP from reaching MongoDB on port 27017
-- **Authentication failures:** Wrong credentials, incorrect `authSource` database, or the user lacking required permissions
-- **Connection pool exhaustion:** Too many concurrent ETL workers exceeding the `maxPoolSize` setting, or connection leaks in application code causing "server selection timed out" errors
-- **SSL/TLS configuration mismatches:** The ETL tool lacking the correct CA certificate to validate the MongoDB server's SSL certificate
-
-**Recommended debug approach:** Test connectivity directly with the MongoDB shell (`mongosh`) using the same connection string first. If that succeeds, the issue is in your ETL tool's configuration — verify credentials, SSL settings, and connection string parameters. If the shell also fails, the issue is at the network or DNS level.
-
-### Q4. How do I handle schema validation errors when MongoDB documents have inconsistent structures?
-Schema validation errors occur because MongoDB allows polymorphic data — documents with varying structures or different data types for the same field — within a single collection. Solutions include:
-
-- **Use schema inference with adequate sampling** — Increase the sample size when inferring the schema so the ETL tool captures the full range of field variations, rather than relying on a small, potentially unrepresentative subset
-- **Mark fields as nullable/optional** for fields that may be absent in some documents
-- **Apply type coercion rules** to handle polymorphic fields by enforcing a consistent target type during ingestion
-- **Filter or quarantine malformed documents** using pre-ingestion validation rules — MongoDB also supports `validationAction: "warn"` mode, which logs invalid documents without rejecting them, making it a useful diagnostic tool during ETL pipeline development
-- **Use a compatible ETL tool** that natively supports MongoDB's BSON types (including `Decimal128`, `ObjectID`) and flexible schema evolution
-
-### Q5. What are best practices for MongoDB ETL setup in production environments?
-For production MongoDB ETL pipelines:
-
-- **Use a dedicated read-only ETL user** with the minimum permissions required — typically `read` on source collections and `clusterMonitor` for oplog access
-- **Connect to a replica set secondary** to avoid adding read load to the primary node
-- **Implement checkpointing using resume tokens** so failed syncs resume from the last successfully processed oplog position rather than restarting from scratch — store the resume token durably and pass it back on reconnection
-- **Monitor oplog lag actively** — a small oplog (e.g., 1GB on a high-throughput cluster) may only retain a few hours of changes; if your CDC consumer falls behind the retention window, you will need to trigger a full resync
-- **Test oplog partial-update handling in staging** before deploying to production — MongoDB's `$set` update operator produces partial update events in the oplog (not full document replacements), and many ETL tools handle these differently; validate that your tool correctly reconstructs the full document from partial oplog events before going live
-
+<Faq showHeading={false} data={[
+  {
+    question: "Q1. What are the most common MongoDB ETL errors and how do you diagnose them?",
+    answer: <ul>
+      <li><strong>Connection timeout errors.</strong> The job fails before reading any data. Diagnose by checking network connectivity to the host, firewall or security group rules blocking port 27017, and your MongoDB authentication credentials.</li>
+      <li><strong>Schema validation failures.</strong> Records get rejected at the destination. Diagnose by sampling documents in the collection and looking for polymorphic fields or required fields missing across documents.</li>
+      <li><strong>Data type mismatch errors.</strong> A column fails to write or values get coerced unexpectedly. Diagnose by comparing the source field type against the target column type for the field named in the error.</li>
+      <li><strong>Socket timeout (<code>socketTimeoutMS</code>) exhaustion during large collection scans.</strong> A query runs longer than the configured <code>socketTimeoutMS</code> and the connection drops mid-scan. Diagnose by comparing query duration against <code>socketTimeoutMS</code> and checking whether the query uses an index. Raise <code>socketTimeoutMS</code> and add indexes so reads avoid full collection scans.</li>
+    </ul>
+  },
+  {
+    question: "Q2. How should I set up MongoDB for ETL to minimize pipeline errors?",
+    answer: <div>
+      <p>Best practices for an ETL-ready MongoDB setup include:</p>
+      <ul>
+        <li><strong>Enable Read Preference on secondary nodes</strong> to offload ETL reads from the primary and avoid impacting operational performance</li>
+        <li><strong>Create indexes on user-defined timestamp fields</strong> (such as an application-managed <code>updated_at</code> field) used for cursor-based incremental sync</li>
+        <li><strong>Set <code>socketTimeoutMS</code> and <code>serverSelectionTimeoutMS</code></strong> appropriately per operation for long-running collection reads</li>
+        <li><strong>Configure oplog retention</strong> to cover at least 24–48 hours of changes to ensure CDC consumers do not fall behind the retention window</li>
+        <li><strong>Ensure a replica set is configured</strong> this is a hard requirement for change streams and oplog-based CDC; standalone MongoDB instances do not support these features</li>
+      </ul>
+    </div>
+  },
+  {
+    question: "Q3. What causes connection timeout errors in MongoDB ETL pipelines and how do I fix them?",
+    answer: <div>
+      <p>Connection timeouts typically occur due to:</p>
+      <ul>
+        <li><strong>Network/firewall issues.</strong> Firewall or security group rules blocking the ETL tool's IP from reaching MongoDB on port 27017. Fix: allowlist the ETL tool's IP or subnet on port 27017 and confirm the route with <code>telnet host 27017</code> or <code>nc -zv host 27017</code>.</li>
+        <li><strong>Authentication failures.</strong> Wrong credentials, incorrect <code>authSource</code> database, or the user lacking required permissions. Fix: verify the credentials, set <code>authSource</code> to the database where the user was created (often <code>admin</code>), and grant the user read access to the source collections.</li>
+        <li><strong>Connection pool exhaustion.</strong> Too many concurrent ETL workers exceeding the <code>maxPoolSize</code> setting, or connection leaks causing "server selection timed out" errors. Fix: raise <code>maxPoolSize</code> to cover your worker count, or lower worker concurrency so it stays within the pool, and make sure connections are closed after each task.</li>
+        <li><strong>SSL/TLS configuration mismatches.</strong> The ETL tool lacking the correct CA certificate to validate the MongoDB server's SSL certificate. Fix: point the connection at the right CA bundle with <code>tlsCAFile</code>, and confirm the host matches the certificate's subject so validation passes.</li>
+      </ul>
+      <p><strong>Recommended debug approach:</strong> Test connectivity directly with the MongoDB shell (<code>mongosh</code>) using the same connection string first. If that succeeds, the issue is in your ETL tool's configuration. If the shell also fails, the issue is at the network or DNS level.</p>
+    </div>
+  },
+  {
+    question: "Q4. How do I handle schema validation errors when MongoDB documents have inconsistent structures?",
+    answer: <div>
+      <p>Schema validation errors occur because MongoDB allows polymorphic data within a single collection. Solutions include:</p>
+      <ul>
+        <li><strong>Use schema inference with adequate sampling.</strong> Increase the sample size so the ETL tool captures the full range of field variations</li>
+        <li><strong>Mark fields as nullable/optional</strong> for fields that may be absent in some documents</li>
+        <li><strong>Apply type coercion rules</strong> to handle polymorphic fields by enforcing a consistent target type during ingestion</li>
+        <li><strong>Filter or quarantine malformed documents</strong> using pre-ingestion validation rules. MongoDB's <code>validationAction: "warn"</code> mode logs invalid documents without rejecting them, useful during pipeline development</li>
+        <li><strong>Use a compatible ETL tool</strong> that natively supports MongoDB's BSON types (including <code>Decimal128</code>, <code>ObjectID</code>) and flexible schema evolution</li>
+      </ul>
+    </div>
+  },
+  {
+    question: "Q5. What are best practices for MongoDB ETL setup in production environments?",
+    answer: <div>
+      <p>For production MongoDB ETL pipelines:</p>
+      <ul>
+        <li><strong>Use a dedicated read-only ETL user</strong> with minimum permissions required, typically <code>read</code> on source collections and <code>clusterMonitor</code> for oplog access</li>
+        <li><strong>Implement checkpointing using resume tokens</strong> so failed syncs resume from the last successfully processed oplog position. Store the resume token durably and pass it back on reconnection</li>
+        <li><strong>Monitor oplog lag actively.</strong> A small oplog (e.g., 1GB on a high-throughput cluster) may only retain a few hours of changes; if your CDC consumer falls behind, you will need to trigger a full resync</li>
+        <li><strong>Test oplog partial-update handling in staging</strong> before deploying. MongoDB's <code>$set</code> operator produces partial update events (not full document replacements), and many ETL tools handle these differently</li>
+      </ul>
+    </div>
+  },
+]} />
 
 <BlogCTA/>

blog/2024-09-16-mongodb-etl-challenges.mdx

@@ -563,7 +563,70 @@ By following best practices, such as using CDC, batching, and data validation, c
 
 *4. MongoDB Documentation, "Working with Nested Data," MongoDB.*
 
-
+## FAQs
+<Faq showHeading={false} data={[
+  {
+    question: "Q1. What are the main MongoDB ETL challenges when moving data to a data warehouse?",
+    answer: <div>
+      <p>The four key challenges are:</p>
+      <ol>
+        <li><strong>Schema flexibility:</strong> MongoDB's schema-less design creates inconsistent field structures that clash with rigid warehouse schemas</li>
+        <li><strong>Large initial loads:</strong> Must be parallelized and checkpointed to handle terabyte-scale collections reliably</li>
+        <li><strong>Changing data types (polymorphic keys):</strong> The same field can appear as different types across documents (e.g., <code>age</code> as an integer in one document and a string in another)</li>
+        <li><strong>Complex nested fields and arrays:</strong> Must be transformed into a flat relational format without causing row explosion or data duplication</li>
+      </ol>
+    </div>
+  },
+  {
+    question: "Q2. How does MongoDB's schema flexibility create problems during ETL to structured systems?",
+    answer: <div>
+      <p>MongoDB allows any document to omit fields or use different types for the same field across documents. When moving this data to relational warehouses or Iceberg tables that require consistent schemas, you encounter:</p>
+      <ul>
+        <li><strong>Type mismatches:</strong> A field that is an integer in some documents and a string in others</li>
+        <li><strong>Missing values:</strong> Sparse fields that exist in only a subset of documents require NULL-filling across the rest</li>
+        <li><strong>Inconsistent nesting structures:</strong> The same logical field may appear as a simple string in one document and a nested object in another</li>
+      </ul>
+      <p>ETL pipelines must detect and resolve these variations without silently dropping or corrupting data.</p>
+    </div>
+  },
+  {
+    question: "Q3. What is the best approach for handling the first full load of a large MongoDB collection?",
+    answer: <div>
+      <p>For large collections, parallelize the initial load using <strong><code>_id</code>-based range queries or bucket-based partitioning</strong> to split the collection into independent read ranges, then load those ranges concurrently across multiple worker threads.</p>
+      <p>Key practices to follow:</p>
+      <ul>
+        <li><strong>Implement checkpointing</strong> so that if the load fails mid-way, it resumes from the last successfully completed chunk rather than restarting from scratch</li>
+        <li><strong>Read from a replica set secondary</strong> to avoid load on the primary during the bulk read</li>
+        <li><strong>Record the oplog timestamp or resume token</strong> at the start of the full load so that incremental CDC replication can pick up exactly from that point once the snapshot completes</li>
+      </ul>
+      <p>After the full load completes, switch to <strong>change streams or oplog-based CDC</strong> for ongoing incremental replication.</p>
+    </div>
+  },
+  {
+    question: "Q4. How should you handle array fields when doing MongoDB ETL to a relational target?",
+    answer: <div>
+      <p>Arrays in MongoDB documents should generally be <strong>exploded into separate child tables</strong> with foreign key references to the parent document. Strategies by array type:</p>
+      <ul>
+        <li><strong>Arrays of simple values:</strong> Create a child table with a <code>parent_id</code> column and a <code>value</code> column. Each array element becomes one row.</li>
+        <li><strong>Arrays of complex objects:</strong> Each object in the array becomes a full row in the child table, with all object fields mapped to columns and a foreign key back to the parent.</li>
+      </ul>
+      <p><strong>Avoid flattening arrays inline:</strong> this causes row explosion and massive data duplication, making the final dataset several times larger than the original.</p>
+      <p>For arrays you do not need for analytics, consider skipping them entirely during extraction rather than flattening unnecessarily.</p>
+    </div>
+  },
+  {
+    question: "Q5. How do you handle polymorphic data types in MongoDB ETL pipelines?",
+    answer: <div>
+      <p>Polymorphic fields, where the same key holds values of different types across documents, can be addressed using one of these strategies:</p>
+      <ul>
+        <li><strong>Type promotion.</strong> Promote all values to the most permissive compatible type (e.g., convert both integers and strings to <code>string</code>). Use numeric type promotions where safe (e.g., <code>int</code> to <code>long</code>, <code>float</code> to <code>double</code>). Best when the types are compatible and you want a single clean column. Avoid it when promoting to <code>string</code> would lose type information you need downstream.</li>
+        <li><strong>Separate typed columns.</strong> Create distinct columns per data type (e.g., <code>age_int</code> and <code>age_string</code>). Older data stays in the original column; new data with a different type populates the new column. Best when you need to preserve every value losslessly and downstream consumers can handle querying across columns. The tradeoff is a wider, sparser table.</li>
+        <li><strong>Schema inference with sampling.</strong> Run a sampling step across the collection before defining your pipeline schema, to determine the dominant type for each field and surface polymorphic fields early. Best as a first step before any pipeline run, so you choose the right handling strategy instead of discovering type conflicts mid-sync.</li>
+        <li><strong>JSON/variant column.</strong> Store the field as a semi-structured column and handle parsing in downstream transformations. Best when types are unpredictable or change often and you want to defer parsing. Only available when your target warehouse natively supports it, such as Snowflake's <code>VARIANT</code>, BigQuery's <code>JSON</code>, or Redshift's <code>SUPER</code>.</li>
+      </ul>
+    </div>
+  },
+]} />
 
 I’d love to hear your thoughts about this, so feel free to reach out to me on [LinkedIn](https://www.linkedin.com/in/zriyansh/).