KV store endpoint descriptions
This introduction describes syntax common to all app KV Store REST endpoints. For more information about the KV Store, see App Key Value Store on the Splunk developer portal.
REST API usage details
Review ACL information for an endpoint
To check Access Control List (ACL) properties for an endpoint, append /acl to the path. For more information see Access Control List in the REST API User Manual.
Authentication and Authorization
Username and password authentication is required for access to endpoints and REST operations.
Splunk users must have role and/or capability-based authorization to use REST endpoints. Users with an administrative role, such as admin, can access authorization information in Splunk Web. To view the roles assigned to a user, select Settings > Access controls and click Users. To determine the capabilities assigned to a role, select Settings > Access controls and click Roles.
App and user context
Typically, knowledge objects, such as saved searches or event types, have an app/user context that is the namespace. For more information about specifying a namespace, see Namespace in the REST API User Manual.
Splunk Cloud limitations
If you have a managed Splunk Cloud deployment with search head clustering and index clustering, the REST API supports access to the search head only. You can use the REST API to interact with the search head in your deployment. Using the REST API to access any other cluster member nodes is not supported. For example, KV store endpoints are not applicable to Splunk Cloud deployments.
App KV Store REST API features
The app KV Store provides the following functions.
- Create, read, list and delete EAI operations on a collection.
- Create, read, list and delete indexes for a given collection. All collection methods are EAI-compatible. These are not regular EAI operations because the indexes are stored as attributes on the EAI entity. Users must have collection permission to use these operations for a particular collection.
- The ability to insert, read, update and delete a single key and key value, for a given collection, provided that you have permission to modify the collection.
- Duplicate keys are not allowed.
- All updates are wholesale updates.
- Partial value updates are not available.
- The ability to query key-value pairs, for a given collection. For example, to find all the documents that have a host field with a value, use the query
{"host": "bar.com"}.
Only the following operations are permitted.
$gt$gte$lt$lte$ne$and$or,$not.
The API also supports mechanisms for projection, sorting and pagination.
- Batch reads, inserts, and/or updates for a given collection. This supports high-volume operations and limits network traffic. These operations have the same semantics as their individual counterparts.
Limits
- 16MB per record
- 1KB per accelerated field
Collections
A Collection is a container of "documents" or "values". Most documents have a similar structure, although structure is not enforced. For example, a Collection might have Notable Events or entities.
Collections are declared in a collections.conf configuration file, where a stanza is a single collection.
Collection permissioning
Collections are Splunk entities, which means they are permissioned using the Splunk RBAC/ACL system. Only app-level permissions are available for collections. This means that collections can be defined only in the etc/apps/<app>/<default|local> directory, not in etc/users/.... Attempts to create a user-specific Collection using the API fail and Collections created manually in the .conf files are ignored.
Data
A collection stores key-value pairs consisting of a user-specified or autogenerated key and a JSON document-formatted value. A JSON document/object of values is enforced for simplicity instead of using integer or string raw values. For example, {"_key": "10.0.0.1", host: "bar.com"} defines the key ("10.0.0.1") and the full JSON document value.
A key is fetched, updated, and deleted. Partial updates, including array append, are not available. You must set the whole document. Keys are unique within a collection and support only the basic JSON data types: boolean, string, number, object, array, and null.
A value is specified in the _key attribute of the document and, if one is not specified, a random value with a desirable sort order is automatically generated.
A collection is defined in the following directory location.
/servicesNS/nobody/search/storage/collections/mycollection
You can use the following URLs to access the collection.
/servicesNS/nobody/search/storage/collections/mycollection/servicesNS/itay/search/storage/collections/mycollection/servicesNS/mark/search/storage/collections/mycollection
Namespaces are separate and data are not interleaved. Wildcard operations on the <user> or <app> parts of the namespace are not available.
User-specific collections are not supported. All users, including nobody, share a single namespace and _key is unique across all namespaces.
Types
You can define a set of types for some fields in a collection. If a field has no type defined, it uses the type submitted over the API. If a type conversion fails, the insert/update operation is aborted.
Here is an example collection in collections.conf.
[mycollection] field.enabled = bool field.data.range = cidr
The data inserted or updated in this collection have the fields enabled and range-converted to the applicable type.
* array * number * boolean * time * string * cidr
Items need to be specified using the field prefix only if type needs to be enforced for the field. The array type is not enforceable so does not need to be specified.
Arrays
Arrays do not change a nested key name. For example, the key "a.b.c" can refer to {"a": {"b": {"c": 1}}} or {"a": {"b": [{"c": 1}]}}.
Numbers
All strings/numbers/booleans are converted to doubles. If a number fails to convert, it inserts the string instead.
Booleans
All numbers/strings/booleans are converted to booleans. If a boolean fails to convert, it inserts the string instead. Epoch time can be a string or a number. If it fails to convert, the string version is inserted.
Strings
Everything is converted to a string.
CIDR
All provided strings are converted to canonical CIDR strings. Here is an example.
127.0.0.1 -> 127.000.000.001/32 127.0.0.0/24 -> 127.000.000.000/24 127.0.0/24 -> 127.000.000.000/24
Here is an example of similar canonicalization for IPv6.
2001:db8::/96 -> 2001:0db8:0000:0000:0000:0000:0000:0000/096 2001:db8:0:0:0:0:0:ffff -> 2001:0db8:0000:0000:0000:0000:0000:ffff/128
Queries
Combining the Data and Index patterns gives the ability to do basic querying. Queries are limited to the basic operators available in most databases, and at the moment do not expose in-array and not-in-array containers. A query can have the following operators.
gtgteltlteeqneqorandnot
Queries are permitted regardless of whether an index covers the query. If it the index does not cover the query, the query takes longer to complete. For example, here is a query to find all Notable Events authored by userA or userB.
{ $or: [ { "author": "userA" }, { "author": "userB" } ] }
Use $and to search for a range of values. For example, use the following query to find all events with a time field value between 12 and 13.
{ "$and": [ { "time": { "$gt": "12" } }, { "time": { "$lt": "13" } } ] }
REST methods
The REST API for App KV Store implements the GET, POST, and DELETE methods described in this reference.
Defining KV Store lookups
For information on using the REST API to define or update a KV Store lookup, see data/transforms/lookups/ and data/transforms/lookups/{name}.
kvstore/backup/create
https://<host>:<mPort>/services/kvstore/backup/create
POST
Create a KV Store backup archive file.
Usage details
Request parameters
| Name | Type | Description |
|---|---|---|
| archiveName | String | Optional. Specify a file name for the backup. |
| appName | String | Optional. Specify a target collection for backup, rather than all of the KV Store. |
| collectionName | String | Optional. Specify a target app for backup, rather than all of the KV Store. |
Returned values
| Name | Description |
|---|---|
| status | Code 200 for success, and code 404 for failure.
|
Example request and response
XML request
curl -k -u admin:changed -X POST https://localhost:8089/services/kvstore/backup/create -d 'archiveName=sampleArchive&appName=search&collectionName=testcollection'
XML response
<title>kvstorebackup</title>
<id>https://localhost:8089/services/kvstore/backup</id>
<updated>2018-04-05T14:18:14-07:00</updated>
<generator build="dbd2996dbabd8f6751329c845684e0ffc9d1cca3" version="20180302"/>
<author>
<name>Splunk</name>
</author>
<link href="/services/kvstore/backup/_acl" rel="_acl"/>
<opensearch:totalResults>0</opensearch:totalResults>
<opensearch:itemsPerPage>30</opensearch:itemsPerPage>
<opensearch:startIndex>0</opensearch:startIndex>
<s:messages/>
kvstore/backup/restore
https://<host>:<mPort>/services/kvstore/backup/restore
POST
Extracts the KV store backup archive file and restores the KV store.
Usage details
Request parameters
| Name | Type | Description |
|---|---|---|
| archiveName | String | Required. Specifies the name of the backup file. |
| appName | String | Optional. Specify a target collection to restore, rather than the entire contents of the archive file. |
| collectionName | String | Optional. Specify a target app to restore, rather than the entire contents of the archive file. |
Returned values
| Name | Description |
|---|---|
| status | Code 200 for success, and code 404 for failure.
|
Example request and response
XML request
curl -k -u admin:changed -X POST https://localhost:8089/services/kvstore/backup/restore -d 'archiveName=kvdump.tar.gz&appName=search&collectionName=testcollection'
XML response
<title>kvstorebackup</title>
<id>https://localhost:8089/services/kvstore/backup</id>
<updated>2018-04-05T14:10:00-07:00</updated>
<generator build="dbd2996dbabd8f6751329c845684e0ffc9d1cca3" version="20180302"/>
<author>
<name>Splunk</name>
</author>
<link href="/services/kvstore/backup/_acl" rel="_acl"/>
<opensearch:totalResults>0</opensearch:totalResults>
<opensearch:itemsPerPage>30</opensearch:itemsPerPage>
<opensearch:startIndex>0</opensearch:startIndex>
<s:messages/>
kvstore/status
https://<host>:<mPort>/services/kvstore/status
Access KV store status information for standalone or search head clustering (SHC) deployments. For SHC deployments, provides information on SHC members where KV Store is enabled and used for replication.
See also the following KV Store introspection endpoints.
- server/introspection/kvstore
- server/introspection/kvstore/collectionstats
- server/introspection/kvstore/replicasetstats
- server/introspection/kvstore/serverstatus
GET
Access KV store status information.
Usage details
Request parameters
None.
Returned values
| Name | Description |
|---|---|
| current | Includes the following indicators for the machine making the GET request.
|
| Enabled KV Store members | Returned for SHC deployments. Lists the following values for SHC members where KV Store is enabled and used for replication.
|
| members | For KV Store members, lists the following indicators.
|
Example request and response
XML request
curl -k -u admin:changed https://localhost:8089/services/kvstore/status
XML response
<title>kvstorestatus</title>
<id>https://localhost:8089/services/kvstore/status</id>
<updated>2016-09-09T15:04:35-07:00</updated>
<generator build="c9afb322d148" version="6.5.0"/>
<author>
<name>Splunk</name>
</author>
<link href="/services/kvstore/status/_acl" rel="_acl"/>
<opensearch:totalResults>1</opensearch:totalResults>
<opensearch:itemsPerPage>30</opensearch:itemsPerPage>
<opensearch:startIndex>0</opensearch:startIndex>
<s:messages/>
<entry>
<title>status</title>
<id>https://localhost:8089/services/kvstore/status/status</id>
<updated>2016-09-09T15:04:35-07:00</updated>
<link href="/services/kvstore/status/status" rel="alternate"/>
<author>
<name>system</name>
</author>
<link href="/services/kvstore/status/status" rel="list"/>
<content type="text/xml">
<s:dict>
<s:key name="current">
<s:dict>
<s:key name="backupRestoreStatus">Ready</s:key>
<s:key name="date">Fri Sep 9 15:04:35 2016</s:key>
<s:key name="dateSec">1473458675.554000</s:key>
<s:key name="disabled">0</s:key>
<s:key name="guid">B4E173F1-02AA-4D46-9DDC-ECF0016F165E</s:key>
<s:key name="oplogEndTimestamp">Fri Sep 9 14:17:01 2016</s:key>
<s:key name="oplogEndTimestampSec">1473455821.000000</s:key>
<s:key name="oplogStartTimestamp">Fri Sep 9 07:16:53 2016</s:key>
<s:key name="oplogStartTimestampSec">1473430613.000000</s:key>
<s:key name="port">8191</s:key>
<s:key name="replicaSet">B4E173F1-02AA-4D46-9DDC-ECF0016F165E</s:key>
<s:key name="replicationStatus">KV store captain</s:key>
<s:key name="standalone">1</s:key>
<s:key name="status">ready</s:key>
</s:dict>
</s:key>
<s:key name="eai:acl">
<s:dict>
<s:key name="app"></s:key>
<s:key name="can_list">1</s:key>
<s:key name="can_write">1</s:key>
<s:key name="modifiable">0</s:key>
<s:key name="owner">system</s:key>
<s:key name="perms">
<s:dict>
<s:key name="read">
<s:list>
<s:item>admin</s:item>
<s:item>splunk-system-role</s:item>
</s:list>
</s:key>
<s:key name="write">
<s:list>
<s:item>admin</s:item>
<s:item>splunk-system-role</s:item>
</s:list>
</s:key>
</s:dict>
</s:key>
<s:key name="removable">0</s:key>
<s:key name="sharing">system</s:key>
</s:dict>
</s:key>
<s:key name="members">
<s:dict>
<s:key name="0">
<s:dict>
<s:key name="configVersion">1</s:key>
<s:key name="electionDate">Fri Sep 9 07:16:53 2016</s:key>
<s:key name="electionDateSec">1473430613.000000</s:key>
<s:key name="hostAndPort">127.0.0.1:8191</s:key>
<s:key name="lastHeartbeat"></s:key>
<s:key name="lastHeartbeatRecv"></s:key>
<s:key name="lastHeartbeatRecvSec"></s:key>
<s:key name="lastHeartbeatSec"></s:key>
<s:key name="optimeDate">Fri Sep 9 14:17:01 2016</s:key>
<s:key name="optimeDateSec">1473455821.000000</s:key>
<s:key name="pingMs"></s:key>
<s:key name="replicationStatus">KV store captain</s:key>
<s:key name="uptime">28071</s:key>
</s:dict>
</s:key>
</s:dict>
</s:key>
</s:dict>
</content>
</entry>
storage/collections/config
https://<host>:<mPort>/servicesNS/{owner}/{app}/storage/collections/config
Access and create collections.
GET
List all collections.
Request parameters
None.
Returned values
| Name | Description |
|---|---|
| disabled | Boolean indicating collection state. By default, the value is false, indicating that the collection is enabled.
|
| profilingEnabled | Boolean indicating profiling status of slow-running operations. By default, this value is false, meaning that profiling is disabled.
|
| profilingThresholdMs | Threshold for logging slow-running operations, in milliseconds. Applies only if profilingEnabled is true.
|
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/config
XML Response
...
<title>collections-conf</title> <id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config</id> <updated>2014-09-02T11:28:27-07:00</updated> <generator build="229629" version="6.2"/>
<author>
<name>Splunk</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/_new" rel="create"/>
<link href="/servicesNS/nobody/search/storage/collections/config/_reload" rel="_reload"/>
... opensearch nodes elided ...
<s:messages/>
<entry>
<title>kvstoredemo</title>
<id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config/kvstoredemo</id>
<updated>2014-09-02T11:28:27-07:00</updated>
<link href="/servicesNS/nobody/search/storage/collections/config/kvstoredemo" rel="alternate"/>
<author>
<name>admin</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/kvstoredemo" rel="list"/>
<link href="/servicesNS/nobody/search/storage/collections/config/kvstoredemo/_reload" rel="_reload"/>
<link href="/servicesNS/nobody/search/storage/collections/config/kvstoredemo" rel="edit"/>
<link href="/servicesNS/nobody/search/storage/collections/config/kvstoredemo" rel="remove"/>
<link href="/servicesNS/nobody/search/storage/collections/config/kvstoredemo/disable" rel="disable"/>
<content type="text/xml">
<s:dict>
<s:key name="disabled">0</s:key>
<s:key name="eai:acl"> ... elided ... </s:key>
<s:key name="eai:appName">search</s:key>
<s:key name="eai:userName">nobody</s:key>
<s:key name="profilingEnabled">false</s:key>
<s:key name="profilingThresholdMs">100</s:key>
</s:dict>
</content>
</entry>
<entry>
<title>test</title>
<id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config/test</id>
<updated>2014-09-02T11:28:27-07:00</updated>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="alternate"/>
<author>
<name>admin</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="list"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test/_reload" rel="_reload"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="edit"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="remove"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test/disable" rel="disable"/>
<content type="text/xml">
<s:dict>
<s:key name="disabled">0</s:key>
<s:key name="eai:acl"> ... elided ...</s:key>
<s:key name="eai:appName">search</s:key>
<s:key name="eai:userName">nobody</s:key>
<s:key name="profilingEnabled">false</s:key>
<s:key name="profilingThresholdMs">100</s:key>
</s:dict>
</content>
</entry>
POST
Create a collection.
Request parameters
| Name | Type | Description |
|---|---|---|
| name | String | Required. Collection name |
| profilingEnabled | Boolean | A collections.conf file property that affects profilingThresholdMs. Defaults to false. Enable profiling of slow-running operations by setting profilingEnabled to true.
|
| profilingThresholdMs | Number | Threshold for logging slow-running operations, in milliseconds. Applies only if profilingEnabled is true. Defaults to 100. Set to 0 to log all slow-running operations.
|
Returned values
| Name | Description |
|---|---|
| disabled | Boolean indicating collection state. By default, the value is false, indicating that the collection is enabled.
|
| profilingEnabled | Profiling status of slow-running operations, profilingThresholdMs. Defaults to false.
|
| profilingThresholdMs | Threshold for logging slow-running operations, in milliseconds. Applies only if profilingEnabled is true.
|
Example request and response
XML Request
curl -k -u admin:changeme -d name=test1 https://localhost:8089/servicesNS/nobody/search/storage/collections/config
XML Response
...
<title>collections-conf</title> <id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config</id> <updated>2014-09-02T11:25:32-07:00</updated> <generator build="229629" version="6.2"/>
<author>
<name>Splunk</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/_new" rel="create"/>
<link href="/servicesNS/nobody/search/storage/collections/config/_reload" rel="_reload"/>
... opensearch nodes elided ...
<s:messages/>
<entry>
<title>test1</title>
<id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config/test1</id>
<updated>2014-09-02T11:25:32-07:00</updated>
<link href="/servicesNS/nobody/search/storage/collections/config/test1" rel="alternate"/>
<author>
<name>admin</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/test1" rel="list"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test1/_reload" rel="_reload"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test1" rel="edit"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test1" rel="remove"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test1/disable" rel="disable"/>
<content type="text/xml">
<s:dict>
<s:key name="disabled">0</s:key>
<s:key name="eai:acl"> ... elided ... </s:key>
<s:key name="eai:appName">search</s:key>
<s:key name="eai:userName">nobody</s:key>
<s:key name="profilingEnabled">false</s:key>
<s:key name="profilingThresholdMs">100</s:key>
</s:dict>
</content>
</entry>
storage/collections/config/{collection}
https://<host>:<mPort>/servicesNS/{owner}/{app}/storage/collections/config/{collection}
Access, delete, or update a specific {collection}.
DELETE
Delete a specific {collection}.
Request parameters
None
Returned values
None
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/config/test -X DELETE
XML Response
... <title>collections-conf</title> <id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config</id> <updated>2014-06-02T20:08:11-07:00</updated> <generator build="210538" version="20140530"/> <author> <name>Splunk</name> </author> <link href="/servicesNS/nobody/search/storage/collections/config/_new" rel="create"/> <link href="/servicesNS/nobody/search/storage/collections/config/_reload" rel="_reload"/> ... opensearch nodes elided ... <s:messages/>
GET
Access a specific {collection}.
Request parameters
None
Returned values
| Name | Description |
|---|---|
| disabled | Boolean indicating collection state. By default, the value is 0, meaning that the collection is enabled.
|
| field.<fieldType> | Field type. One of the following values.
|
| accelerated_fields.<field_name> | Field acceleration name and JSON definition. |
| enforceTypes | Boolean indicating if data types are enforced when inserting data into the collection. Defaults to false.
|
| profilingEnabled | Profiling status of slow-running operations, affecting profilingThresholdMs. By default, the value is false, meaning that profiling is disabled. If true, profiling is enabled.
|
| profilingThresholdMs | Threshold for logging slow-running operations, in milliseconds. Applies only if profilingEnabled is true.
|
| replicate | Boolean indicating whether the collection is replicated on indexers. Defaults to false, meaning that this collection is not replicated, and lookups that depend on the collection will not be available. However, if you run a lookup command with local=true, local lookups will still be available.When true, this collection is replicated on indexers.
|
| replication_dump_maximum_file_size | Indicates the maximum file size (in KB) for each dump file when replication_dump_strategy=auto. Defaults to 10240KB.If this value is larger than concerningReplicatedFileSize, which is set in the distsearch.conf file, the value of concerningReplicatedFileSize is used instead. KV Store does not pre-calculate the size of the records that will be written to disk, so the size of the resulting files can be affected by the max_rows_in_memory_per_dump setting in the limits.conf file.
|
| replication_dump_strategy | One of the following two values.
|
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/collections/config/test
XML Response
...
<title>collections-conf</title> <id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config</id> <updated>2014-09-02T11:42:54-07:00</updated> <generator build="229629" version="6.2"/>
<author>
<name>Splunk</name>
</author> <link href="/servicesNS/nobody/search/storage/collections/config/_new" rel="create"/> <link href="/servicesNS/nobody/search/storage/collections/config/_reload" rel="_reload"/> ... opensearch nodes elided ... <s:messages/> <entry>
<title>test</title>
<id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config/test</id>
<updated>2014-09-02T11:42:54-07:00</updated>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="alternate"/>
<author>
<name>admin</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="list"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test/_reload" rel="_reload"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="edit"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="remove"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test/disable" rel="disable"/>
<content type="text/xml">
<s:dict>
<s:key name="disabled">0</s:key>
<s:key name="eai:acl"> ... elided ... </s:key>
<s:key name="eai:appName">search</s:key>
<s:key name="eai:attributes"> ... elided ... </s:key>
<s:key name="eai:userName">nobody</s:key>
<s:key name="profilingEnabled">false</s:key>
<s:key name="profilingThresholdMs">100</s:key>
</s:dict>
</content>
</entry>
POST
Update a specific {collection}.
Request parameters
| Name | Type | Description |
|---|---|---|
| field.<fieldType> | String | Field type. One of the following values.
|
| accelerated_fields.<field_name> | String, JSON (see description) | The name of a field acceleration (string) and its definition, in JSON key value format. For example, accelerated_fields.my_accel = {"id": 1}
|
Returned values
| Name | Description |
|---|---|
| disabled | Collection state:true = disabled.false = [Default] enabled.
|
| field.<fieldType> | Field type. One of the following values.
|
| accelerated_fields.<field_name> | The name of a field acceleration (string) and its definition, in JSON key value format. For example, accelerated_fields.my_accel = {"id": 1}
|
| profilingEnabled | Profiling status of slow-running operations, affecting profilingThresholdMs. By default, the value is false, meaning that profiling is disabled. If true, profiling is enabled.
|
| profilingThresholdMs | Threshold for logging slow-running operations, in milliseconds. Applies only if profilingEnabled is true.
|
| replicate | Boolean indicating whether the collection is replicated on indexers. Defaults to false, meaning that this collection is not replicated, and lookups that depend on the collection will not be available. However, if you run a lookup command with local=true, local lookups will still be available.When true, this collection is replicated on indexers.
|
| replication_dump_maximum_file_size | Indicates the maximum file size (in KB) for each dump file when replication_dump_strategy=auto. Defaults to 10240KB.If this value is larger than concerningReplicatedFileSize, which is set in the distsearch.conf file, the value of concerningReplicatedFileSize is used instead. KV Store does not pre-calculate the size of the records that will be written to disk, so the size of the resulting files can be affected by the max_rows_in_memory_per_dump setting in the limits.conf file.
|
| replication_dump_strategy | One of the following two values.
|
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/config/test -d 'accelerated_fields.foo={"a": 1}' -d 'accelerated_fields.bar={"b": -1}' -d "field.a=number" -d "field.b=cidr"
XML Response
...
<title>collections-conf</title> <id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config</id> <updated>2014-09-02T11:50:57-07:00</updated> <generator build="229629" version="6.2"/>
<author>
<name>Splunk</name>
</author> <link href="/servicesNS/nobody/search/storage/collections/config/_new" rel="create"/> <link href="/servicesNS/nobody/search/storage/collections/config/_reload" rel="_reload"/> ... opensearch nodes elided ... <s:messages/> <entry>
<title>test</title>
<id>https://localhost:8089/servicesNS/nobody/search/storage/collections/config/test</id>
<updated>2014-09-02T11:50:57-07:00</updated>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="alternate"/>
<author>
<name>admin</name>
</author>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="list"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test/_reload" rel="_reload"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="edit"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test" rel="remove"/>
<link href="/servicesNS/nobody/search/storage/collections/config/test/disable" rel="disable"/>
<content type="text/xml">
<s:dict>
<s:key name="disabled">0</s:key>
<s:key name="eai:acl"> ... elided ... </s:key>
<s:key name="eai:appName">search</s:key>
<s:key name="eai:userName">nobody</s:key>
<s:key name="accelerated_fields.foo">{"a": 1}
accelerated_fields.bar={"b": -1} field.a=number field.b=cidr</s:key>
<s:key name="profilingEnabled">false</s:key>
<s:key name="profilingThresholdMs">100</s:key>
</s:dict>
</content>
</entry>
storage/collections/data/{collection}
https://<host>:<mPort>/servicesNS/{owner}/{app}/storage/collections/data/{collection}
Access and manage items of a collection.
DELETE
Delete items in the {collection} or delete an entire collection.
Usage details
Use the query parameter to specify which entries to delete. If no query is provided, all entries in the collection are deleted.
Request parameters
| Name | Type | Description |
|---|---|---|
| query | JSON object | Query JSON object. Conditional operators: $gt, $gte, $lt, $lte, and $neLogical operators: $and, $or, and ,$not (invert conditional operators)Examples: query={"title":"Item"} (Select all documents with property title that has value Item)query={"price":{"$gt":5}} (Select all documents with price greater than 5)
|
Returned values
None
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/data/testCollectionA -X DELETE
XML Response
No values returned.
GET
Access a specific {collection}.
Request parameters
Parameter order in the request does not matter. Parameters are always applied in the order of sort, skip, and limit.
| Name | Type | Description |
|---|---|---|
| fields | String | Comma-separated list of fields to include (1) or exclude (0). A fields value cannot contain both include and exclude specifications except for exclusion of the _key field. Examples:fields=firstname,surname (Include only firstname, surname, and _key fields)fields=firstname,surname,_key:0 (Include only the firstname and surname fields.fields=address:0 (Include all fields except the address field)
|
| limit | Number | Maximum number of items to return. For example, to return five items, use limit=5.
|
| skip | Number | Number of items to skip from the start. For example, to skip the first ten items, use skip=10.
|
| sort | String | Sort order. Examples:sort=surname (Sort by surname, ascending)sort=surname,firstname (Sort by surname, ascending, after firstname, ascending)sort=surname:-1,firstname:1 (Sort by surname, descending, after firstname, ascendingsort=surname:1,first name (Sort by surname, ascending, after firstname, ascending
|
| query | JSON object | Query JSON object. Conditional operators: $gt, $gte, $lt, $lte, and $neLogical operators: $and, $or, and ,$not (invert conditional operators)Examples: query={"title":"Item"} (Select all documents with property title that has value Item)query={"price":{"$gt":5}} (Select all documents with price greater than 5)
|
Returned values
The response includes a JSON document.
Example
[ { "myKey" : "abc", "_user" : "nobody", "_key" : "5410be5441ba15298e4624d1" } ]
POST
Insert an item into the {collection}.
Usage details
The Content-Type header must be application/json.
The _key is autogenerated, if not manually specified.
Request parameters
Make sure that the item to add is a JSON-formatted document, such as the following example.
{ "name": "A" }
Returned values
The response includes a JSON-formatted document key, such as the following example.
{
"_key": "530bc62fc9a6577fdf13651f"
}
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/data/testCollectionA -H "Content-Type: application/json" -d '{ "myKey": "abc", "myOtherKey": "abcdef"}'
XML Response
{"_key":"5410be5441ba15298e4624d1"}
storage/collections/data/{collection}/{key}
https://<host>:<mPort>/servicesNS/{owner}/{app}/storage/collections/data/{collection}/{key}
Access and manage a specific {key} item in a {collection}.
DELETE
Delete a collection item.
Request parameters
None
Returned values
None
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/collections/data/testCollectionA/5410caf041ba15298e4624d6 -X DELETE
XML Response
No values returned.
GET
Access a collection item.
Request parameters
None
Returned values
The response includes a JSON-formatted {key} document, such as the following example.
{"myKey" : "abc", "myOtherKey" : "uvwxyz", "_user" : "nobody", "_key" : "5410c8dc41ba15298e4624d5"}
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/collections/data/testCollectionA/5410c8dc41ba15298e4624d5
XML Response
{ "myKey" : "abc", "myOtherKey" : "uvwxyz", "_user" : "nobody", "_key" : "5410c8dc41ba15298e4624d5" }
POST
Update a collection item.
Usage details
The header Content-Type must be application/json.
Request parameters
Pass in a JSON-formatted document for the {key} that you are updating. For example, use { "myKey": "fizz"}.
Returned values
The response includes a JSON-formatted {key} such as the following example.
{"_key":"5410c8dc41ba15298e4624d5"}
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/data/testCollectionA/5410c8dc41ba15298e4624d5 -H "Content-Type: application/json" -d '{ "myKey": "fizz"}'
XML Response
{"_key":"5410c8dc41ba15298e4624d5"}
storage/collections/data/{collection}/batch_save
https://<host>:<mPort>/servicesNS/storage/collections/data/{collection}/batch_save
Perform multiple save operations in a batch.
POST
Perform multiple save operations in a batch.
Usage details
The request header Content-Type must be application/json.
If a document does not have a _key field or store does not have a matching document ID, a _key new document is created.
If an operation fails, the server stops batch processing and returns an HTTP status code other than 200.
Request parameters
Pass in the JSON array of documents to save.
Returned values
The response includes a JSON-formatted list of keys added, such as the following example.
[ "5410c43241ba15298e4624d3", "5418c54e41ba152267763c01" ]
Example request and response
XML Request
curl -k -u admin:changeme https://localhost:8089/servicesNS/nobody/search/storage/collections/data/testCollectionA/batch_save -H "Content-Type: application/json" -d '[{ "_key": "5410c43241ba15298e4624d3", "name": "AAAAAAAA" },{ "name": "A" }]'
XML Response
[ "5410c43241ba15298e4624d3", "5418c54e41ba152267763c01" ]
| Knowledge endpoint descriptions | License endpoint descriptions |
This documentation applies to the following versions of Splunk® Enterprise: 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10
Download manual
Feedback submitted, thanks!