temporalio/temporal · error

SearchPrecision is required when searching for a StartTime o

Error message

SearchPrecision is required when searching for a StartTime or CloseTime

What it means

This error comes from the GCloud archive visibility query parser (common/archiver/gcloud/query_parser.go). When a workflow visibility query filters on StartTime or CloseTime, exactly one of those must be present AND a SearchPrecision (Day/Hour/Minute/Second) must also be supplied. The parser throws this when a time filter is present but SearchPrecision is missing, because the blobstore-based archiver needs the precision to bucket scans of time-partitioned objects.

Source

Thrown at common/archiver/gcloud/query_parser.go:72

}

func (p *queryParser) Parse(query string) (*parsedQuery, error) {
	stmt, err := sqlparser.Parse(fmt.Sprintf(sqlquery.QueryTemplate, query))
	if err != nil {
		return nil, err
	}
	whereExpr := stmt.(*sqlparser.Select).Where.Expr
	parsedQuery := &parsedQuery{}
	if err := p.convertWhereExpr(whereExpr, parsedQuery); err != nil {
		return nil, err
	}

	if (parsedQuery.closeTime.IsZero() && parsedQuery.startTime.IsZero()) || (!parsedQuery.closeTime.IsZero() && !parsedQuery.startTime.IsZero()) {
		return nil, errors.New("requires a StartTime or CloseTime")
	}

	if parsedQuery.searchPrecision == nil {
		return nil, errors.New("SearchPrecision is required when searching for a StartTime or CloseTime")
	}

	return parsedQuery, nil
}

func (p *queryParser) convertWhereExpr(expr sqlparser.Expr, parsedQuery *parsedQuery) error {
	if expr == nil {
		return errors.New("where expression is nil")
	}

	switch expr := expr.(type) {
	case *sqlparser.ComparisonExpr:
		return p.convertComparisonExpr(expr, parsedQuery)
	case *sqlparser.AndExpr:
		return p.convertAndExpr(expr, parsedQuery)
	case *sqlparser.ParenExpr:
		return p.convertParenExpr(expr, parsedQuery)
	default:

View on GitHub (pinned to bde624efd1)

Solutions

1. Add a SearchPrecision condition to the WHERE clause, e.g. `SearchPrecision = "Day"`, alongside the single StartTime or CloseTime filter.
2. Ensure exactly one of StartTime or CloseTime is present; both missing or both present triggers the sibling "requires a StartTime or CloseTime" error first.
3. Use one of the supported precision values: Day, Hour, Minute, Second.
4. If this query is intended for Elasticsearch/SQL visibility, point it at that visibility store instead of the GCloud archival visibility store, which does not require SearchPrecision.

Example fix

// before
q := "CloseTime BETWEEN '2024-01-01T00:00:00Z' AND '2024-01-02T00:00:00Z'"
parsed, err := gcloud.NewQueryParser().Parse(q)
// error: SearchPrecision is required when searching for a StartTime or CloseTime

// after
q := "CloseTime BETWEEN '2024-01-01T00:00:00Z' AND '2024-01-02T00:00:00Z' AND SearchPrecision = 'Day'"
parsed, err := gcloud.NewQueryParser().Parse(q)

func hasTimeWithoutPrecision(q string) bool {
	ql := strings.ToLower(q)
	hasTime := strings.Contains(ql, "starttime") || strings.Contains(ql, "closetime")
	return hasTime && !strings.Contains(ql, "searchprecision")
}
// if hasTimeWithoutPrecision(query) { add `AND SearchPrecision = 'Day'` or reject }

When it happens

Trigger: Calling gcloud.NewQueryParser().Parse(query) (or a GCloud visibility archiver that uses it) with a WHERE clause containing StartTime or CloseTime but no `SearchPrecision = "Hour"` (or Day/Minute/Second) condition. Parse runs the full SQL parse and where-expression conversion first, so the query must otherwise be valid to reach this check.

Common situations: Users running `temporal workflow list --query` against GCloud archival visibility with queries like `WHERE StartTime > '2024-01-01T00:00:00Z'` copied from Elasticsearch/SQL-style visibility examples that do not require SearchPrecision. Also happens when a query builder omits the precision clause or when upgrading from a visibility store that did not need it.

Related errors

• where expression is nil
• only comparison and "and" expression is supported
• where expression is nil
• unknown filter name: %s
• only comparison and "and" expression is supported

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/17df477b810a63ef. Report an issue: GitHub.