In order to execute a scan using the Scan API, an as_scan object must be initialized and populated.
Before using an as_scan, it must be initialized via either:
as_scan_init() should be used on a stack allocated as_scan. It will initialize the as_scan with the given namespace and set. On success, it will return a pointer to the initialized as_scan. Otherwise, NULL is returned.
as_scan_new() should be used to allocate and initialize a heap allocated as_scan. It will allocate the as_scan, then initialized it with the given namespace and set. On success, it will return a pointer to the initialized as_scan. Otherwise, NULL is returned.
When you are finished with the as_scan, you can destroy it and associated resources:
An initialized as_scan can be populated with additional fields.
as_scan_select() is used to specify the bins to be selected by the scan. If a scan specifies bins to be selected, then only those bins will be returned. If no bins are selected, then all bins will be returned.
Before adding bins to select, the select structure must be initialized via either:
Both functions are given the number of bins to be selected.
A complete example using as_scan_select_inita()
A scan can return only record meta data, and exclude bins.
A scan can be made to scan all the nodes in parallel
A scan can define the percentage of record in the cluster to be scaned.
To set the priority of the scan, the set as_scan.priority.
The priority of a scan can be defined as either:
AS_SCAN_PRIORITY_AUTO
AS_SCAN_PRIORITY_LOW
AS_SCAN_PRIORITY_MEDIUM
AS_SCAN_PRIORITY_HIGH
A UDF can be applied to each record scanned.
To define the UDF for the scan, use as_scan_apply_each().
#include "as_scan.h"
Data Fields | |
as_udf_call | apply_each |
bool | concurrent |
bool | deserialize_list_map |
bool | no_bins |
as_namespace | ns |
struct as_operations_s * | ops |
bool | paginate |
as_partitions_status * | parts_all |
as_scan_bins | select |
as_set | set |
uint32_t | ttl |
Related Functions | |
(Note that these are not member functions.) | |
AS_EXTERN bool | as_scan_apply_each (as_scan *scan, const char *module, const char *function, as_list *arglist) |
AS_EXTERN bool | as_scan_compare (as_scan *s1, as_scan *s2) |
AS_EXTERN void | as_scan_destroy (as_scan *scan) |
AS_EXTERN bool | as_scan_from_bytes (as_scan *scan, const uint8_t *bytes, uint32_t bytes_size) |
AS_EXTERN as_scan * | as_scan_from_bytes_new (const uint8_t *bytes, uint32_t bytes_size) |
AS_EXTERN as_scan * | as_scan_init (as_scan *scan, const char *ns, const char *set) |
static bool | as_scan_is_done (as_scan *scan) |
AS_EXTERN as_scan * | as_scan_new (const char *ns, const char *set) |
AS_EXTERN bool | as_scan_select (as_scan *scan, const char *bin) |
AS_EXTERN bool | as_scan_select_init (as_scan *scan, uint16_t n) |
AS_EXTERN bool | as_scan_set_nobins (as_scan *scan, bool nobins) |
static void | as_scan_set_paginate (as_scan *scan, bool paginate) |
static void | as_scan_set_partitions (as_scan *scan, as_partitions_status *parts_all) |
AS_EXTERN bool | as_scan_to_bytes (const as_scan *scan, uint8_t **bytes, uint32_t *bytes_size) |
|
related |
Apply a UDF to each record scanned on the server.
scan | The scan to apply the UDF to. |
module | The module containing the function to execute. |
function | The function to execute. |
arglist | The arguments for the function. |
Releases all resources allocated to the scan.
|
related |
Deserialize bytes to scan definition. Scan definition is assumed to be on the stack. as_scan_destroy() should be called when done with the scan definition.
Create scan definition on the heap and deserialize bytes to that scan definition. as_scan_destroy() should be called when done with the scan definition.
Initializes a scan.
When you no longer require the scan, you should release the scan and related resources via as_scan_destroy()
.
scan | The scan to initialize. |
ns | The namespace to scan. |
set | The set to scan. |
|
related |
If using scan pagination, did previous paginated scan with this scan instance return all records?
Definition at line 593 of file as_scan.h.
References as_partitions_status::done, and parts_all.
Create and initializes a new scan on the heap.
When you no longer require the scan, you should release the scan and related resources via as_scan_destroy()
.
ns | The namespace to scan. |
set | The set to scan. |
Select bins to be projected from matching records.
You have to ensure as_scan.select has sufficient capacity, prior to adding a bin. If capacity is insufficient then false is returned.
scan | The scan to modify. |
bin | The name of the bin to select. |
Initializes as_scan.select
with a capacity of n
using malloc()
.
For stack allocation, use as_scan_select_inita()
.
scan | The scan to initialize. |
n | The number of bins to allocate. |
Do not return bins. This will only return the metadata for the records.
scan | The scan to set the priority on. |
nobins | If true, then do not return bins. |
|
related |
Set to true if as_policy_scan.max_records is set and you need to scan data in pages.
Definition at line 567 of file as_scan.h.
References paginate.
|
related |
Set completion status of all partitions from a previous scan that ended early. The scan will resume from this point.
Definition at line 580 of file as_scan.h.
References as_partitions_status_reserve(), and parts_all.
|
related |
Serialize scan definition to bytes.
as_udf_call as_scan::apply_each |
UDF to apply to results of the background scan.
Should be set via as_scan_apply_each()
.
bool as_scan::concurrent |
bool as_scan::deserialize_list_map |
bool as_scan::no_bins |
as_namespace ns |
Namespace to be scanned.
Should be initialized via either:
struct as_operations_s* as_scan::ops |
Perform write operations on a background scan. If ops is set, ops will be destroyed when as_scan_destroy() is called.
bool as_scan::paginate |
Set to true if as_policy_scan.max_records is set and you need to scan data in pages.
Default: false
as_partitions_status* as_scan::parts_all |
as_scan_bins as_scan::select |
Name of bins to select.
Use either of the following function to initialize:
Use as_scan_select() to populate.
as_set as_scan::set |
Set to be scanned.
Should be initialized via either:
uint32_t as_scan::ttl |
The time-to-live (expiration) of the record in seconds. Note that ttl is only used on background scan writes.
There are also special values that can be set in the record ttl: