> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textql.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MongoDB Connector

> Query your MongoDB collections in Ana using native aggregation pipelines.

### **1. Overview**

The Ana x MongoDB integration connects your MongoDB cluster to Ana, giving you natural language access to your collections. MongoDB is a document database, so Ana queries it with native **aggregation pipelines** (`db.<collection>.aggregate([...])`) rather than SQL — collections appear as tables, nested document fields are exposed as dot-paths (`address.city`), and arrays can be `$unwind`-ed. Results come back as a normal table.

<Note>
  Connect MongoDB to Ana to query and analyze your collections using natural language.
</Note>

### **2. Prerequisites**

You'll need:

* A MongoDB cluster you want Ana to query — MongoDB Atlas or a self-managed deployment
* A **read-only** database user, and permission to view the cluster's connection string
* A TextQL account with permission to add connectors

<Warning>
  Use a **read-only** MongoDB user for this connector. Ana only issues read queries, but aggregation pipelines can technically include write stages (`$out`, `$merge`) — a read-only user guarantees the connector can never modify your data regardless of the query. In Atlas, assign the built-in **`readAnyDatabase`** role, or **`read`** on a specific database.
</Warning>

### Which type of connection should I use?

| | **SRV (Atlas)** | **Direct host and port** |
| - | - | - |
| **Best For** | MongoDB Atlas clusters | Self-managed deployments and replica sets you address directly |
| **Connection string** | `mongodb+srv://…` | `mongodb://…` |
| **How hosts resolve** | Cluster members discovered via DNS SRV records | The single host and port you supply |
| **Port** | Not used — leave the default | Required (default `27017`) |
| **TLS** | Implied by SRV, and required by Atlas | Enable it unless your deployment has TLS turned off |

### **3. Capabilities**

Once configured, Ana can:

* Query any collection in plain language and return the results as a table.
* Aggregate across documents — group, filter, and summarize without hand-written pipelines.
* Read nested fields as dot-paths and expand arrays where a question needs per-element rows.
* Query across every database in the cluster, or stay scoped to one.

### **4. Setup Instructions**

***

### Step 1: Gather your MongoDB connection details

<Tabs>
  <Tab title="MongoDB Atlas">
    1. Go to [cloud.mongodb.com](https://cloud.mongodb.com) and sign in.
    2. Navigate to your cluster and click **Connect**.
    3. Choose **Drivers**.
    4. Under step 3, MongoDB shows a connection string like:

       ```
       mongodb+srv://db_user:<db_password>@cluster0.7fmjzec.mongodb.net/?appName=Cluster0
       ```

       You need only the **host** from it — the part between `@` and `/`. In this example that's `cluster0.7fmjzec.mongodb.net`. Don't paste the whole string into TextQL.
    5. Note the username, and the password for that database user. Atlas does not show an existing user's password again — if you don't have it, reset it under **Database Access**, or create a new read-only user there.
    6. Under **Network Access**, add your TextQL egress IP to the allowlist. See the [Network Configuration Guide](/core/datasources/databases/network-configuration) for the addresses to allow.
  </Tab>

  <Tab title="Self-managed">
    1. Collect the **hostname or IP** of your deployment and the **port** it listens on (default `27017`).
    2. Collect the credentials for a read-only user, and note the database that user authenticates against — this is the **Auth Source**, and it's `admin` in most deployments.
    3. Confirm whether the deployment requires TLS.
    4. Make sure the deployment is reachable from TextQL. See the [Network Configuration Guide](/core/datasources/databases/network-configuration) for firewall and IP allowlisting.
  </Tab>
</Tabs>

### **Step 2: Add MongoDB as a connector in TextQL**

1. Go to the [TextQL Connectors Page](https://app.textql.com/connectors) and sign in.
2. Click **New Connector** and select **MongoDB**.
3. Fill in two fields:
   * **Connector Name** — a descriptive name for this connection.
   * **Host** — the host from Step 1, on its own, with no `mongodb+srv://` prefix and no trailing path (e.g. `cluster0.7fmjzec.mongodb.net`).
4. For MongoDB Atlas, turn on **Use SRV connection (mongodb+srv, for Atlas)**. For a self-managed deployment, leave it off and enter the deployment's **Port** instead.
5. Click **Create Connector**.

The remaining fields already hold working defaults — leave them as they are unless your deployment needs otherwise.

<Tip>
  Leaving **Database** blank exposes every non-system database, with collections referenced as `database.collection`. This requires the connector's user to hold the `listDatabases` privilege — if it doesn't have that, name a single database in the form instead.
</Tip>

### **Step 3: Verify the connection**

1. Open the MongoDB connector and click **Test Connection**.

* A successful setup returns a connection confirmation.
* If the test fails, see the [Troubleshooting](#6-troubleshooting) section below.

***

### **5. Usage Examples**

Once configured, you can ask Ana:

* "How many documents are in the orders collection, and how has that grown by month?"
* "Break down users by the city in their address field."
* "Which products appear most often across all order line items?"
* "Show me the orders collection's fields and what types they hold."
* "Compare average order value between customers acquired this year and last."

### **6. Troubleshooting**

| **Symptom** | **Likely Cause** | **Fix** |
| - | - | - |
| Connection times out | TextQL's egress IP isn't allowlisted | In Atlas, add it under **Network Access**. For self-managed deployments, open the port to TextQL — see the [Network Configuration Guide](/core/datasources/databases/network-configuration). |
| Authentication failed | Wrong password, or the user authenticates against a different database | Confirm the credentials, then check **Auth Source** — it's `admin` for most Atlas users. Reset the password under Atlas **Database Access** if you don't have it. |
| Host not found | The full connection string was pasted into **Host** | Enter only the host — no `mongodb+srv://` prefix, no `/?appName=…` suffix. |
| No collections appear | **Database** was left blank but the user lacks `listDatabases` | Name a database explicitly in the form, or grant the privilege. |
| A query fails on a write stage | The pipeline included `$out` or `$merge` | Expected with a read-only user. Rephrase the question so it only reads. |

### **7. Security Notes**

* Follow the principle of least privilege. Grant the connector's user read access only to the data Ana needs — `readAnyDatabase`, or `read` on a single database.
* Keep **Use TLS** enabled so credentials and query results are encrypted in transit. Atlas requires it.
* Keep the Atlas **Network Access** allowlist as narrow as possible rather than opening the cluster to all addresses.
* Credentials are stored encrypted by TextQL. Rotate the database user's password if you suspect it has been exposed, and update the connector afterwards.
* If you no longer need the integration, remove the connector in TextQL and delete the database user in MongoDB.

***

### **Need Help?**

For further assistance, please contact [support@textql.com](mailto:support@textql.com).

### **Privacy Policy**

For information about how we handle your data and protect your privacy, please review our [Privacy Policy](https://textql.com/privacy).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.