QueryMind

QueryMind lets you query MySQL and MongoDB databases with natural language. The Node.js package connects your backend service to QueryMind, your database, and your Qdrant vector store so you can ingest schema context, generate queries, execute them, explain results, and create chart specifications.

Installation

npm install querymind

Install the database driver you use:

npm install mysql2
# or
npm install mongodb

Import

import QueryMind from "querymind"

const QueryMind = require("querymind")

Create a client

MySQL

const querymind = new QueryMind(process.env.QUERYMIND_API_KEY, {
  dbType: "MYSQL",
  qdrant: {
    url: "http://localhost:6333",
    apiKey: process.env.QDRANT_API_KEY,
  },
  mysql: {
    host: "localhost",
    database: "analytics",
    userName: "root",
    password: process.env.MYSQL_PASSWORD,
    port: 3306,
  },
  timeout: 3600000,
})

MongoDB

const querymind = new QueryMind(process.env.QUERYMIND_API_KEY, {
  dbType: "MONGODB",
  qdrant: {
    url: "http://localhost:6333",
    apiKey: process.env.QDRANT_API_KEY,
  },
  mongodb: {
    host: "mongodb://localhost:27017",
    database: "analytics",
  },
})

Recommended setup flow

Run setup once when creating or refreshing a workspace:

await querymind.verify()

const schema = await querymind.extractSchema()
await querymind.ingestSchema(schema)

const result = await querymind.search("Show my top customers this month", 10)
console.log(result.rows)

For large schemas, split tables or collections into smaller chunks and call ingestSchema for each chunk.

Query examples

Generate a query without executing it:

const query = await querymind.generateQuery("Top 10 customers by revenue", 10)

console.log(query.sql || query.pipeline)

Generate and execute a query:

const result = await querymind.search("Show monthly sales for this year", 12)

console.log(result.fields)
console.log(result.rows)

Generate, execute, and explain results:

const result = await querymind.searchExplain(
  "Why did revenue change last month?",
  20
)

console.log(result.rows)
console.log(result.content)

Execute a manual SQL query:

const result = await querymind.searchQuery({
  sql: "SELECT * FROM orders LIMIT 10",
  dbName: "reporting",
})

Execute a manual MongoDB aggregation:

const result = await querymind.searchQuery({
  collection: "orders",
  pipeline: [{ $limit: 10 }],
  dbName: "analytics_prod",
})

Create a chart specification from rows:

const result = await querymind.search("Sales by region", 100)
const chartSpec = await querymind.generateChart(result.rows)

Validate generated queries

Pass a validator callback to generateQuery, search, or searchExplain to inspect, reject, or modify AI-generated queries before they are returned or executed.

const result = await querymind.search(
  "Show recent orders",
  25,
  (query, context) => {
    if (query.sql?.toLowerCase().includes("drop ")) {
      throw new Error("Unsafe query")
    }

    return {
      ...query,
      dbName: "reporting",
    }
  }
)

The callback receives:

{
  question: "Show recent orders",
  limit: 25,
  dbType: "MYSQL",
  dbName: "analytics"
}

Return a modified query object, or return nothing to keep the generated query unchanged.

API reference

verify()

Checks database, Qdrant, and QueryMind API access. It also ensures the Qdrant collections for this API key exist.

remove()

Removes Qdrant collections created for this API key. Use this when resetting or deprovisioning a workspace.

extractSchema()

Reads your configured MySQL or MongoDB database and returns schema data that can be passed to ingestSchema.

ingestSchema(schema)

Uploads schema metadata to QueryMind and stores embeddings in Qdrant.

generateQuery(question, limit?, validateQuery?)

Generates SQL or a MongoDB aggregation pipeline from a natural-language question. This does not execute the query.

search(question, limit?, validateQuery?)

Generates and executes a query against the configured database.

searchExplain(question, limit?, validateQuery?)

Generates and executes a query, then returns the rows with an AI-generated explanation in content.

searchQuery(query)

Executes a manually supplied SQL string, SQL object, or MongoDB query object.

await querymind.searchQuery("SELECT * FROM orders LIMIT 10")

searchQueryExplain(question, query)

Executes a supplied query and explains the returned data for the original question.

generateChart(rows)

Generates a chart specification from result rows.

Return shape

Search methods return tabular data:

{
  fields: ["id", "name", "total"],
  rows: [
    { id: 1, name: "Acme", total: 2500 }
  ],
  content: "Optional explanation from searchExplain or searchQueryExplain"
}

Configuration

| Option | Required | Description | | --- | --- | --- | | apiKey | Yes | QueryMind API key. Pass as the first constructor argument. | | dbType | Yes | Database type. Supported values are MYSQL and MONGODB. | | qdrant.url | Yes | Qdrant server URL. | | qdrant.apiKey | No | Qdrant API key, when your Qdrant instance requires one. | | mysql.host | MySQL only | MySQL host. | | mysql.database | MySQL only | MySQL database name. | | mysql.userName | MySQL only | MySQL user name. | | mysql.password | No | MySQL password. | | mysql.port | No | MySQL port. | | mongodb.host | MongoDB only | MongoDB connection string. | | mongodb.database | MongoDB only | MongoDB database name. | | timeout | No | Request timeout in milliseconds. Defaults to 3600000. |

Security notes

Use this package from trusted backend code only. Do not expose QueryMind, database, or Qdrant credentials in browser code.

QueryMind stores schema and query context embeddings in your configured Qdrant instance. Methods such as searchExplain, searchQueryExplain, and generateChart send returned rows to QueryMind to generate explanations or chart specs, so call them only with result data you are comfortable using for those features.

License

MIT