stoty commented on code in PR #6498: URL: https://github.com/apache/hbase/pull/6498#discussion_r1870721385
########## src/main/asciidoc/_chapters/external_apis.adoc: ########## @@ -406,6 +442,107 @@ has been exhausted, HTTP status `204` is returned. |=== +[[stateless.scanner.endpoints]] +.Endpoints of Stateless Scanner +[options="header", cols="2m,m,3d,6l"] +|=== +|Endpoint +|HTTP Verb +|Description +|Example + +|/_table_/* +|GET +|Scanning the entire table. The stateless scanner endpoint does not require a followup call to return the results. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*"; + +|/_table_/*?limit=_number_of_rows_ +|GET +|Scanning the first row of the table. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?limit=1"; + +|/_table_/*?column=_column:qualifier_ +|GET +|Scanning a given column of the table. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?column=cf:a"; + +|/_table_/*?column=_column1:qualifier1_,_column2:qualifier2_ +|GET +|Scanning more than one column of the table. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?column=cf:a,cf:b"; + +|/_table_/*?startrow=_row_&limit=_number_of_rows_ +|GET +|Scanning table with start row and limit. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?startrow=row1&limit=2"; + +|/_table_/_row_prefix_* +|GET +|Scanning table with row prefix. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/row1*"; + +|/_table_/*?reversed=true +|GET +|Scanning table in reverse. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?reversed=true"; + +|/_table_/*?filter=_url_encoded_filter_ +|GET +|Scanning with a filter `PrefixFilter('row1')`. The filter should be specified according to the <<thrift.filter_language,Thrift Filter Language>> and then encoded as `application/x-www-form-urlencoded` MIME format string. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?filter=PrefixFilter%28%27row1%27%29"; + +|/_table_/*?filter_b64=_b64_encoded_filter_ +|GET +|Scanning with a filter `PrefixFilter('row1')`. The filter should be specified according to the <<thrift.filter_language,Thrift Filter Language>> and then encoded in https://datatracker.ietf.org/doc/html/rfc4648#section-5[URL-safe base64]. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?filter_b64=UHJlZml4RmlsdGVyKCdyb3cxJyk"; + +|=== + +The <<stateful.scanner.endpoints,stateful scanner API>> expects clients to restart scans if there is a REST server failure in the midst. +The stateless does not store any state related to scan operation and all the parameters are specified as query parameters. + +The following are the scan parameters: + +* `startrow` - The start row for the scan. +* `endrow` - The end row for the scan. +* `column` - The comma separated list of columns to scan. +* `starttime`, `endtime` - To only retrieve columns within a specific range of version timestamps, both start and end time must be specified. +* `maxversions` - To limit the number of versions of each column to be returned. +* `batchsize` - To limit the maximum number of values returned for each call to next(). +* `limit` - The number of rows to return in the scan operation. +* `cacheblocks` - Whether to use the <<perf.hbase.client.blockcache,Block Cache>> in the RegionServer. By default `true`. +* `reversed` - When set to `true`, reverse scan will be executed. By default `false`. +* `filter` - Allows to specify a filter for the scan as an `application/x-www-form-urlencoded` MIME format string. +* `filter_b64` - Allows to specify a filter for the scan, encoded in https://datatracker.ietf.org/doc/html/rfc4648#section-5[URL-safe base64]. When both `filter` and `filter_b64` are specified, only `filter_b64` is considered. +* `includeStartRow` - Whether start row should be included in the scan. By default `true`. +* `includeStopRow` - Whether end row (stop row) should be included in the scan. By default `false`. Review Comment: Add a note that this is only supported on versions that include HBASE-28627, and that version without that patch will either ignore these parameters or will error out if they are set to a non-default value. ########## src/main/asciidoc/_chapters/external_apis.adoc: ########## @@ -341,7 +376,8 @@ curl -vi -X DELETE \ |=== -.Endpoints for `Scan` Operations +[[stateful.scanner.endpoints]] +.Endpoints of Stateful Scanner Review Comment: The same goes for the title of the stateless endpoints. ########## src/main/asciidoc/_chapters/external_apis.adoc: ########## @@ -341,7 +376,8 @@ curl -vi -X DELETE \ |=== -.Endpoints for `Scan` Operations +[[stateful.scanner.endpoints]] +.Endpoints of Stateful Scanner Review Comment: A better name would be "Stateful endpoints for scan operations", as it's the endpoint that is stateful/stateless, not the scanner operation. ########## src/main/asciidoc/_chapters/external_apis.adoc: ########## @@ -406,6 +442,107 @@ has been exhausted, HTTP status `204` is returned. |=== +[[stateless.scanner.endpoints]] +.Endpoints of Stateless Scanner +[options="header", cols="2m,m,3d,6l"] +|=== +|Endpoint +|HTTP Verb +|Description +|Example + +|/_table_/* +|GET +|Scanning the entire table. The stateless scanner endpoint does not require a followup call to return the results. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*"; + +|/_table_/*?limit=_number_of_rows_ +|GET +|Scanning the first row of the table. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?limit=1"; + +|/_table_/*?column=_column:qualifier_ +|GET +|Scanning a given column of the table. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?column=cf:a"; + +|/_table_/*?column=_column1:qualifier1_,_column2:qualifier2_ +|GET +|Scanning more than one column of the table. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?column=cf:a,cf:b"; + +|/_table_/*?startrow=_row_&limit=_number_of_rows_ +|GET +|Scanning table with start row and limit. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?startrow=row1&limit=2"; + +|/_table_/_row_prefix_* +|GET +|Scanning table with row prefix. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/row1*"; + +|/_table_/*?reversed=true +|GET +|Scanning table in reverse. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?reversed=true"; + +|/_table_/*?filter=_url_encoded_filter_ +|GET +|Scanning with a filter `PrefixFilter('row1')`. The filter should be specified according to the <<thrift.filter_language,Thrift Filter Language>> and then encoded as `application/x-www-form-urlencoded` MIME format string. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?filter=PrefixFilter%28%27row1%27%29"; + +|/_table_/*?filter_b64=_b64_encoded_filter_ +|GET +|Scanning with a filter `PrefixFilter('row1')`. The filter should be specified according to the <<thrift.filter_language,Thrift Filter Language>> and then encoded in https://datatracker.ietf.org/doc/html/rfc4648#section-5[URL-safe base64]. +|curl -vi -X GET \ +-H "Accept: text/xml" \ +"http://example.com:8000/users/*?filter_b64=UHJlZml4RmlsdGVyKCdyb3cxJyk"; + +|=== + +The <<stateful.scanner.endpoints,stateful scanner API>> expects clients to restart scans if there is a REST server failure in the midst. +The stateless does not store any state related to scan operation and all the parameters are specified as query parameters. + Review Comment: Add some explaination that the stateless endpoints are optimized for small results, while the stateful can also be used for large results. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
