From ccfb7c5e29761dfb53d02021f39d801f168c836f Mon Sep 17 00:00:00 2001
From: John Belmonte <john@neggie.net>
Date: Tue, 8 Sep 2020 03:57:34 +0900
Subject: [PATCH] revise /api/v1/series docs (#746)

* revise /api/v1/series docs

Further clarification for #735

  * clarify how default range differers from Prometheus API
  * avoid `start=0` suggestion when confirming delete, because it will cause a timeout in most deployments

* Update README.md
---
 README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 512d0a0a9..bc9482bda 100644
--- a/README.md
+++ b/README.md
@@ -565,11 +565,12 @@ VictoriaMetrics supports the following handlers from [Prometheus querying API](h
 
 These handlers can be queried from Prometheus-compatible clients such as Grafana or curl.
 
+#### Prometheus querying API enhancements
+
 Additionally to unix timestamps and [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) VictoriaMetrics accepts relative times in `time`, `start` and `end` query args.
 For example, the following query would return data for the last 30 minutes: `/api/v1/query_range?start=-30m&query=...`.
 
-VictoriaMetrics returns time series for the last 5 minutes from `/api/v1/series` if `start` query arg is missing there.
-`end` query arg defaults to the current time if it is missing.
+By default, VictoriaMetrics returns time series for the last 5 minutes from /api/v1/series, while the Prometheus API defaults to all time.  Use `start` and `end` to select a different time range.
 
 VictoriaMetrics accepts additional args for `/api/v1/labels` and `/api/v1/label/.../values` handlers.
 See [this feature request](https://github.com/prometheus/prometheus/issues/6178) for details:
@@ -689,8 +690,9 @@ where `<timeseries_selector_for_delete>` may contain any [time series selector](
 for metrics to delete. After that all the time series matching the given selector are deleted. Storage space for
 the deleted time series isn't freed instantly - it is freed during subsequent [background merges of data files](https://medium.com/@valyala/how-victoriametrics-makes-instant-snapshots-for-multi-terabyte-time-series-data-e1f3fb0e0282).
 
-It is recommended verifying which metrics will be deleted with the call to `http://<victoria-metrics-addr>:8428/api/v1/series?match[]=<timeseries_selector_for_delete>&start=0`
-before actually deleting the metrics.
+It is recommended verifying which metrics will be deleted with the call to `http://<victoria-metrics-addr>:8428/api/v1/series?match[]=<timeseries_selector_for_delete>`
+before actually deleting the metrics.  By default this query will only scan active series in the past 5 minutes, so you may need to
+adjust `start` and `end` to a suitable range to achieve match hits.
 
 The `/api/v1/admin/tsdb/delete_series` handler may be protected with `authKey` if `-deleteAuthKey` command-line flag is set.