diff --git a/docs/category.json b/docs/category.json index 7b22ab31fc7..253adc2dc15 100644 --- a/docs/category.json +++ b/docs/category.json @@ -8,7 +8,6 @@ ], "ppl_cli": [ "user/ppl/cmd/ad.rst", - "user/ppl/cmd/bin.rst", "user/ppl/cmd/dedup.rst", "user/ppl/cmd/describe.rst", "user/ppl/cmd/showdatasources.rst", @@ -55,6 +54,7 @@ ], "ppl_cli_calcite": [ "user/ppl/cmd/append.rst", + "user/ppl/cmd/bin.rst", "user/ppl/functions/condition.rst", "user/ppl/cmd/eventstats.rst", "user/ppl/cmd/fields.rst", diff --git a/docs/user/dql/metadata.rst b/docs/user/dql/metadata.rst index b34d5f2c3bc..8135e3684d4 100644 --- a/docs/user/dql/metadata.rst +++ b/docs/user/dql/metadata.rst @@ -35,7 +35,7 @@ Example 1: Show All Indices Information SQL query:: os> SHOW TABLES LIKE '%' - fetched rows / total rows = 17/17 + fetched rows / total rows = 18/18 +----------------+-------------+------------------+------------+---------+----------+------------+-----------+---------------------------+----------------+ | TABLE_CAT | TABLE_SCHEM | TABLE_NAME | TABLE_TYPE | REMARKS | TYPE_CAT | TYPE_SCHEM | TYPE_NAME | SELF_REFERENCING_COL_NAME | REF_GENERATION | |----------------+-------------+------------------+------------+---------+----------+------------+-----------+---------------------------+----------------| @@ -52,6 +52,7 @@ SQL query:: | docTestCluster | null | otellogs | BASE TABLE | null | null | null | null | null | null | | docTestCluster | null | people | BASE TABLE | null | null | null | null | null | null | | docTestCluster | null | state_country | BASE TABLE | null | null | null | null | null | null | + | docTestCluster | null | time_test | BASE TABLE | null | null | null | null | null | null | | docTestCluster | null | weblogs | BASE TABLE | null | null | null | null | null | null | | docTestCluster | null | wildcard | BASE TABLE | null | null | null | null | null | null | | docTestCluster | null | work_information | BASE TABLE | null | null | null | null | null | null | diff --git a/docs/user/ppl/cmd/bin.rst b/docs/user/ppl/cmd/bin.rst index 258f4b64912..1ebdc3f897e 100644 --- a/docs/user/ppl/cmd/bin.rst +++ b/docs/user/ppl/cmd/bin.rst @@ -240,160 +240,146 @@ Example 1: Basic numeric span PPL query:: - ppl> source=accounts | bin age span=10 | fields age | head 3; + os> source=accounts | bin age span=10 | fields age, account_number | head 3; fetched rows / total rows = 3/3 - +-------+ - | age | - |-------| - | 30-40 | - | 35-45 | - | 25-35 | - +-------+ + +-------+----------------+ + | age | account_number | + |-------+----------------| + | 30-40 | 1 | + | 30-40 | 6 | + | 20-30 | 13 | + +-------+----------------+ Example 2: Large numeric span ============================== PPL query:: - ppl> source=accounts | bin balance span=25000 | fields balance | head 2; + os> source=accounts | bin balance span=25000 | fields balance | head 2; fetched rows / total rows = 2/2 - +---------------+ - | balance | - |---------------| - | 0-25000 | - | 25000-50000 | - +---------------+ - -Example 3: Floating point span -=============================== - -PPL query:: - - ppl> source=accounts | bin age span=2.5 | fields age | head 3; - fetched rows / total rows = 3/3 +-------------+ - | age | + | balance | |-------------| - | 27.5-30.0 | - | 30.0-32.5 | - | 35.0-37.5 | + | 25000-50000 | + | 0-25000 | +-------------+ -Example 4: Logarithmic span (log10) + +Example 3: Logarithmic span (log10) ==================================== PPL query:: - ppl> source=accounts | bin balance span=log10 | fields balance | head 2; + os> source=accounts | bin balance span=log10 | fields balance | head 2; fetched rows / total rows = 2/2 +------------------+ | balance | |------------------| - | 1000.0-10000.0 | | 10000.0-100000.0 | + | 1000.0-10000.0 | +------------------+ -Example 5: Logarithmic span with coefficient +Example 4: Logarithmic span with coefficient ============================================= PPL query:: - ppl> source=accounts | bin balance span=2log10 | fields balance | head 3; + os> source=accounts | bin balance span=2log10 | fields balance | head 3; fetched rows / total rows = 3/3 - +-------------------+ - | balance | - |-------------------| - | 200.0-2000.0 | - | 2000.0-20000.0 | - | 20000.0-200000.0 | - +-------------------+ + +------------------+ + | balance | + |------------------| + | 20000.0-200000.0 | + | 2000.0-20000.0 | + | 20000.0-200000.0 | + +------------------+ Bins Parameter Examples ======================= -Example 6: Basic bins parameter +Example 5: Basic bins parameter ================================ PPL query:: - ppl> source=time_test | bin value bins=5 | fields value | head 3; + os> source=time_test | bin value bins=5 | fields value | head 3; fetched rows / total rows = 3/3 - +-------------+ - | value | - |-------------| - | 8000-9000 | - | 7000-8000 | - | 9000-10000 | - +-------------+ - -Example 7: Low bin count + +------------+ + | value | + |------------| + | 8000-9000 | + | 7000-8000 | + | 9000-10000 | + +------------+ + +Example 6: Low bin count ========================= PPL query:: - ppl> source=accounts | bin age bins=2 | fields age | head 1; + os> source=accounts | bin age bins=2 | fields age | head 1; fetched rows / total rows = 1/1 +-------+ | age | |-------| - | 0-100 | + | 30-40 | +-------+ -Example 8: High bin count +Example 7: High bin count ========================== PPL query:: - ppl> source=accounts | bin age bins=21 | fields age | head 3; + os> source=accounts | bin age bins=21 | fields age, account_number | head 3; fetched rows / total rows = 3/3 - +-------+ - | age | - |-------| - | 20-21 | - | 21-22 | - | 22-23 | - +-------+ + +-------+----------------+ + | age | account_number | + |-------+----------------| + | 32-33 | 1 | + | 36-37 | 6 | + | 28-29 | 13 | + +-------+----------------+ Minspan Parameter Examples ========================== -Example 9: Basic minspan +Example 8: Basic minspan ========================= PPL query:: - ppl> source=accounts | bin age minspan=5 | fields age | head 3; + os> source=accounts | bin age minspan=5 | fields age, account_number | head 3; fetched rows / total rows = 3/3 - +-------+ - | age | - |-------| - | 30-35 | - | 35-40 | - | 25-30 | - +-------+ - -Example 10: Large minspan + +-------+----------------+ + | age | account_number | + |-------+----------------| + | 30-40 | 1 | + | 30-40 | 6 | + | 20-30 | 13 | + +-------+----------------+ + +Example 9: Large minspan ========================== PPL query:: - ppl> source=accounts | bin age minspan=101 | fields age | head 1; + os> source=accounts | bin age minspan=101 | fields age | head 1; fetched rows / total rows = 1/1 - +---------+ - | age | - |---------| - | 0-1000 | - +---------+ + +--------+ + | age | + |--------| + | 0-1000 | + +--------+ Start/End Parameter Examples ============================ -Example 11: Start and end range +Example 10: Start and end range ================================ PPL query:: - ppl> source=accounts | bin age start=0 end=101 | fields age | head 1; + os> source=accounts | bin age start=0 end=101 | fields age | head 1; fetched rows / total rows = 1/1 +-------+ | age | @@ -401,26 +387,26 @@ PPL query:: | 0-100 | +-------+ -Example 12: Large end range +Example 11: Large end range ============================ PPL query:: - ppl> source=accounts | bin balance start=0 end=100001 | fields balance | head 1; + os> source=accounts | bin balance start=0 end=100001 | fields balance | head 1; fetched rows / total rows = 1/1 - +-----------+ - | balance | - |-----------| - | 0-100000 | - +-----------+ + +----------+ + | balance | + |----------| + | 0-100000 | + +----------+ -Example 13: Span with start/end +Example 12: Span with start/end ================================ PPL query:: - ppl> source=bank | bin age span=1 start=25 end=35 | fields age | head 6; - fetched rows / total rows = 6/6 + os> source=accounts | bin age span=1 start=25 end=35 | fields age | head 6; + fetched rows / total rows = 4/4 +-------+ | age | |-------| @@ -428,68 +414,66 @@ PPL query:: | 36-37 | | 28-29 | | 33-34 | - | 36-37 | - | 39-40 | +-------+ Time-based Examples =================== -Example 14: Hour span +Example 13: Hour span ====================== PPL query:: - ppl> source=time_test | bin @timestamp span=1h | fields @timestamp, value | head 3; + os> source=time_test | bin @timestamp span=1h | fields @timestamp, value | head 3; fetched rows / total rows = 3/3 +---------------------+-------+ | @timestamp | value | - |---------------------|-------| + |---------------------+-------| | 2025-07-28 00:00:00 | 8945 | | 2025-07-28 01:00:00 | 7623 | | 2025-07-28 02:00:00 | 9187 | +---------------------+-------+ -Example 15: Minute span +Example 14: Minute span ======================== PPL query:: - ppl> source=time_test | bin @timestamp span=45minute | fields @timestamp, value | head 3; + os> source=time_test | bin @timestamp span=45minute | fields @timestamp, value | head 3; fetched rows / total rows = 3/3 +---------------------+-------+ | @timestamp | value | - |---------------------|-------| + |---------------------+-------| | 2025-07-28 00:00:00 | 8945 | | 2025-07-28 01:30:00 | 7623 | | 2025-07-28 02:15:00 | 9187 | +---------------------+-------+ -Example 16: Second span +Example 15: Second span ======================== PPL query:: - ppl> source=time_test | bin @timestamp span=30seconds | fields @timestamp, value | head 3; + os> source=time_test | bin @timestamp span=30seconds | fields @timestamp, value | head 3; fetched rows / total rows = 3/3 +---------------------+-------+ | @timestamp | value | - |---------------------|-------| - | 2025-07-28 00:15:00 | 8945 | + |---------------------+-------| + | 2025-07-28 00:15:30 | 8945 | | 2025-07-28 01:42:00 | 7623 | | 2025-07-28 02:28:30 | 9187 | +---------------------+-------+ -Example 17: Daily span +Example 16: Daily span ======================= PPL query:: - ppl> source=time_test | bin @timestamp span=7day | fields @timestamp, value | head 3; + os> source=time_test | bin @timestamp span=7day | fields @timestamp, value | head 3; fetched rows / total rows = 3/3 +---------------------+-------+ | @timestamp | value | - |---------------------|-------| + |---------------------+-------| | 2025-07-24 00:00:00 | 8945 | | 2025-07-24 00:00:00 | 7623 | | 2025-07-24 00:00:00 | 9187 | @@ -498,31 +482,31 @@ PPL query:: Aligntime Parameter Examples ============================ -Example 18: Aligntime with time modifier +Example 17: Aligntime with time modifier ========================================= PPL query:: - ppl> source=time_test | bin @timestamp span=2h aligntime='@d+3h' | fields @timestamp, value | head 3; + os> source=time_test | bin @timestamp span=2h aligntime='@d+3h' | fields @timestamp, value | head 3; fetched rows / total rows = 3/3 +---------------------+-------+ | @timestamp | value | - |---------------------|-------| + |---------------------+-------| | 2025-07-27 23:00:00 | 8945 | | 2025-07-28 01:00:00 | 7623 | | 2025-07-28 01:00:00 | 9187 | +---------------------+-------+ -Example 19: Aligntime with epoch timestamp +Example 18: Aligntime with epoch timestamp =========================================== PPL query:: - ppl> source=time_test | bin @timestamp span=2h aligntime=1500000000 | fields @timestamp, value | head 3; + os> source=time_test | bin @timestamp span=2h aligntime=1500000000 | fields @timestamp, value | head 3; fetched rows / total rows = 3/3 +---------------------+-------+ | @timestamp | value | - |---------------------|-------| + |---------------------+-------| | 2025-07-27 22:40:00 | 8945 | | 2025-07-28 00:40:00 | 7623 | | 2025-07-28 00:40:00 | 9187 | @@ -531,18 +515,18 @@ PPL query:: Default Binning Example ======================= -Example 20: Default behavior (no parameters) +Example 19: Default behavior (no parameters) ============================================== PPL query:: - ppl> source=accounts | bin age | fields age | head 3; + os> source=accounts | bin age | fields age, account_number | head 3; fetched rows / total rows = 3/3 - +-------+ - | age | - |-------| - | 20-30 | - | 30-40 | - | 40-50 | - +-------+ + +-----------+----------------+ + | age | account_number | + |-----------+----------------| + | 32.0-33.0 | 1 | + | 36.0-37.0 | 6 | + | 28.0-29.0 | 13 | + +-----------+----------------+ diff --git a/doctest/test_data/bank.json b/doctest/test_data/bank.json new file mode 100644 index 00000000000..c9247c77c7e --- /dev/null +++ b/doctest/test_data/bank.json @@ -0,0 +1,10 @@ +{"age":32,"balance":39225,"account_type":"checking","branch":"downtown"} +{"age":36,"balance":5686,"account_type":"savings","branch":"uptown"} +{"age":28,"balance":32838,"account_type":"checking","branch":"downtown"} +{"age":33,"balance":4180,"account_type":"savings","branch":"midtown"} +{"age":29,"balance":18976,"account_type":"checking","branch":"downtown"} +{"age":39,"balance":25467,"account_type":"savings","branch":"uptown"} +{"age":27,"balance":12345,"account_type":"checking","branch":"midtown"} +{"age":35,"balance":41892,"account_type":"savings","branch":"downtown"} +{"age":31,"balance":7654,"account_type":"checking","branch":"uptown"} +{"age":34,"balance":29876,"account_type":"savings","branch":"midtown"} \ No newline at end of file diff --git a/doctest/test_data/time_test.json b/doctest/test_data/time_test.json new file mode 100644 index 00000000000..913091cd14d --- /dev/null +++ b/doctest/test_data/time_test.json @@ -0,0 +1,10 @@ +{"@timestamp":"2025-07-28T00:15:45Z","value":8945} +{"@timestamp":"2025-07-28T01:42:12Z","value":7623} +{"@timestamp":"2025-07-28T02:28:33Z","value":9187} +{"@timestamp":"2025-07-28T03:45:21Z","value":6832} +{"@timestamp":"2025-07-28T04:15:07Z","value":8534} +{"@timestamp":"2025-07-28T05:32:18Z","value":7123} +{"@timestamp":"2025-07-28T06:18:45Z","value":9876} +{"@timestamp":"2025-07-28T07:05:33Z","value":8321} +{"@timestamp":"2025-07-28T08:22:11Z","value":7654} +{"@timestamp":"2025-07-28T09:41:29Z","value":9243} \ No newline at end of file diff --git a/doctest/test_docs.py b/doctest/test_docs.py index 041bb38a5d2..c94378ed537 100644 --- a/doctest/test_docs.py +++ b/doctest/test_docs.py @@ -41,7 +41,8 @@ 'worker': 'worker.json', 'work_information': 'work_information.json', 'events': 'events.json', - 'otellogs': 'otellogs.json' + 'otellogs': 'otellogs.json', + 'time_test': 'time_test.json' } DEBUG_MODE = os.environ.get('DOCTEST_DEBUG', 'false').lower() == 'true'