bytebase/bytebase · warning

MongoDB does not support EXPLAIN

Error message

MongoDB does not support EXPLAIN

What it means

MongoDB has no EXPLAIN-equivalent handled by this driver. When a query arrives through the unified SQL interface with the Explain flag set, the driver rejects the request outright instead of attempting an unsupported execution plan command.

Source

Thrown at backend/plugin/db/mongodb/mongodb.go:186

	if connConfig.DataSource.GetDirectConnection() {
		values.Add("directConnection", "true")
	}

	for k, v := range connConfig.DataSource.GetExtraConnectionParameters() {
		if k == "" {
			continue
		}
		values.Add(k, v)
	}
	u.RawQuery = values.Encode()

	return u.String()
}

// QueryConn queries a SQL statement in a given connection.
func (d *Driver) QueryConn(ctx context.Context, _ *sql.Conn, statement string, queryContext db.QueryContext) ([]*v1pb.QueryResult, error) {
	if queryContext.Explain {
		return nil, errors.New("MongoDB does not support EXPLAIN")
	}

	statement = strings.Trim(statement, " \t\n\r\f;")
	startTime := time.Now()

	gmClient := gomongo.NewClient(d.client)
	var gmOpts []gomongo.ExecuteOption
	if queryContext.Limit > 0 {
		gmOpts = append(gmOpts, gomongo.WithMaxRows(int64(queryContext.Limit)))
	}
	result, err := gmClient.Execute(ctx, d.databaseName, statement, gmOpts...)
	if err != nil {
		return nil, err
	}
	return d.convertGomongoResult(result, statement, startTime), nil
}

func (*Driver) convertGomongoResult(res *gomongo.Result, statement string, startTime time.Time) []*v1pb.QueryResult {

View on GitHub (pinned to 1870550677)

Solutions

1. Don't set queryContext.Explain for MongoDB queries — run the statement normally
2. Hide/disable the explain action in UI/API layers for MongoDB connections
3. If plan inspection is needed, run explain-compatible aggregation stages ($explain or .explain()) directly via a MongoDB client instead
4. Return a structured 'unsupported' result upstream so callers can degrade gracefully

Example fix

// before
queryCtx := db.QueryContext{Explain: true}
results, err := driver.QueryConn(ctx, conn, stmt, queryCtx)
// after
queryCtx := db.QueryContext{Explain: engine != storepb.Engine_MONGODB}
results, err := driver.QueryConn(ctx, conn, stmt, queryCtx)

if engine == storepb.Engine_MONGODB && queryContext.Explain {
	return errors.New("explain is not supported for MongoDB")
}

When it happens

Trigger: QueryConn(ctx, conn, statement, queryContext) invoked with queryContext.Explain == true — e.g. the UI's 'explain' button or an API caller requesting a plan for a MongoDB query.

Common situations: Users clicking explain/plan preview on a MongoDB datasource in the UI; automation that generically sets Explain for all engines; ported tooling that assumed every driver supports EXPLAIN.

Related errors

• cannot get collection name from collection info
• cannot convert collection name to string
• cannot get size from collStats command result
• cannot get totalIndexSize from collStats command result
• cannot get index name from index info

AI-assisted analysis of bytebase/bytebase@1870550677 (2026-09-06). Data as JSON: /api/errors/10b55fa7dac71b2a. Report an issue: GitHub.