wording

api/graphite.go

@@ -1017,9 +1017,8 @@ func (s *Server) graphiteTagFindSeries(ctx *middleware.Context, request models.G
 		return
 	}
 
-	// If limit is specified and less than the global `maxSeriesPerReq` (or `maxSeriesPerReq` is disabled),
-	// then this is a "soft" limit, meaning we stop and don't return an error. If global `maxSeriesPerReq`
-	// exists, then respect that
+	// Out of the provided soft limit and the global `maxSeriesPerReq` hard limit
+	// (either of which may be 0 aka disabled), pick the only one that matters: the most strict one.
 	isSoftLimit := true
 	limit := request.Limit
 	if maxSeriesPerReq > 0 && (limit == 0 || limit > maxSeriesPerReq) {
@@ -1078,6 +1077,8 @@ func (s *Server) graphiteTagFindSeries(ctx *middleware.Context, request models.G
 	}
 }
 
+// clusterFindByTag returns the Series matching the given expressions.
+// If maxSeries is > 0, it specifies a limit which will truncate the resultset (if softLimit is true) or return an error otherwise.
 func (s *Server) clusterFindByTag(ctx context.Context, orgId uint32, expressions tagquery.Expressions, from int64, maxSeries int, softLimit bool) ([]Series, error) {
 	data := models.IndexFindByTag{OrgId: orgId, Expr: expressions.Strings(), From: from}
 	newCtx, cancel := context.WithCancel(ctx)

docs/cloud/http-api.md

@@ -280,7 +280,9 @@ that duplicate entries will be returned.
 * expr (required): a list of [tag expressions](#tag-expressions)
 * from: Graphite [from time specification](#fromto) (optional. defaults to now-24hours)
 * format: series-json, lastts-json. (defaults to series-json)
-* limit: max number to return, 0 to defer to the instance configured max (default: 0). Note: if limit is 0 or greater than the instance configured max and the result set is greater than the instance configured max, an error is returned. Otherwise, the result set is truncated at the limit
+* limit: max number to return. (default: 0)
+  Note: the resultset is also subjected to the cluster configuration.
+  if the result set is larger than the cluster configuration, an error is returned. If it breaches the provided limit, the result is truncated.
 * meta: If false and format is `series-json` then return series names as array (graphite compatibility). If true, include meta information like warnings.  (defaults to false)
 
 ##### Example

docs/http-api.md

@@ -82,7 +82,9 @@ that duplicate entries will be returned.
 * expr (required): a list of [tag expressions](#tag-expressions)
 * from: Graphite [from time specification](#fromto) (optional. defaults to now-24hours)
 * format: series-json, lastts-json. (defaults to series-json)
-* limit: max number to return, 0 to defer to `http.max-series-per-req` (default: 0). Note: if limit is 0 or greater than `http.max-series-per-req` and the result set is greater than `http.max-series-per-req`, an error is returned. Otherwise, the result set is truncated at the limit
+* limit: max number to return. (default: 0)
+  Note: the resultset is also subjected to the `http.max-series-per-req` config setting.
+  if the result set is larger than `http.max-series-per-req`, an error is returned. If it breaches the provided limit, the result is truncated.
 * meta: If false and format is `series-json` then return series names as array (graphite compatibility). If true, include meta information like warnings.  (defaults to false)
 
 ##### Example