You are viewing the documentation for a prerelease version.

View Latest

key

    +
    Provides information on keys.

    Syntax

    cbstats host:11210 [common options] key <keyname> <vbid>
      [<scope>.<collection> | id <collectionID>]

    Options

    For common cbstats options, see the cbstats reference page. Command-specific options are as follows:

    Option Description

    keyname

    Name of the key.

    vbid

    vBucket ID. To find the vBucket ID associated with a given key, use the cbc-hash command; which is available as part of the Couchbase C SDK (libcouchbase). Examples are provided below.

    scope.collection

    The scope and collection that contain the key.

    id collectionID

    The id of the collection that contains the key. For information on retrieving the id of a collection, see the cbstats collections reference page.

    Responses

    Responses contain the following information:

    Stat Value

    key_cas

    The key’s current cas value, as a decimal integer.

    key_exptime

    Expiration time from the epoch, as a decimal integer.

    key_flags

    Flags for this key, as a decimal integer.

    key_is_dirty

    If the value is not yet persisted.

    key_is_resident

    If the value is resident in memory.

    key_valid

    See the description below.

    key_vb_state

    The vBucket state of this key.

    Note that key_valid can have any of the following values:

    • this_is_a_bug. An error has occurred.

    • dirty. The value in memory has not been persisted yet.

    • length_mismatch. The key length in memory does not match the length on the disk.

    • data_mismatch. The data in memory does not match the data on disk.

    • flags_mismatch. The flags in memory do not match the flags on disk.

    • valid. The key is both on disk and in memory.

    • ram_but_not_disk. The value does not yet exist on disk.

    • item_deleted. The item has been deleted.

    Examples: Find vBucket IDs

    Using cbc-hash, the following call searches for the vBucket ID that corresponds to the key airline_10; which is provided by default, in the sample bucket travel-sample:

    /opt/couchbase/bin/cbc-hash airline_10 \
    -U couchbase://localhost/travel-sample \
    -u Administrator -P password

    The response is as follows:

    airline_10: [vBucket=361, Index=0] Server: localhost:11210, CouchAPI: http://localhost:8092/travel-sample

    The response thus indicates that the document with the key airline_10 resides in the vBucket whose id is 361.

    The following call searches for the key of a custom-created document, saved by the administrator in the sample bucket travel-sample:

    /opt/couchbase/bin/cbc-hash newTestDoc \
    -U couchbase://localhost/travel-sample \
    -u Administrator -P password

    The response is as follows:

    newTestDoc: [vBucket=4, Index=0] Server: localhost:11210, CouchAPI: http://localhost:8092/travel-sample

    The response thus indicates that the document with the key newTestDoc resides in the vBucket whose id is 4.

    Examples: Get Key Information

    Key information can be retrieved either by specifying the bucket; or by additionally specifying either a collection or both a scope and a collection, within the bucket.

    Get Key Information, Specifying Bucket

    The following call requests information on the key airline_10, contained in the vBucket whose id is 361:

    /opt/couchbase/bin/cbstats -u Administrator -p password \
    -b travel-sample localhost:11210 \
    key 'airline_10' 361

    The response is as follows:

    key airline_10 361
    stats for key airline_10
     key_cas:         1601426228785053696
     key_exptime:     0
     key_flags:       100663298
     key_is_dirty:    false
     key_is_resident: true
     key_vb_state:    active

    Get Key Information, Specifying Bucket, Scope, and Collection

    The following example requests information on the key airline_10, which is provided by default in the sample bucket travel-sample. The call uses the <scope>.<collection> option, to specify that the default scope and collection should be searched:

    /opt/couchbase/bin/cbstats -u Administrator -p password \
    -b travel-sample localhost:11210 \
    key 'airline_10' 361 _default._default

    The response is as follows:

    key airline_10 361 _default._default
    stats for key airline_10
     key_cas:         1601426228785053696
     key_exptime:     0
     key_flags:       100663298
     key_is_dirty:    false
     key_is_resident: true
     key_vb_state:    active

    The following example, again using the <scope>.<collection> option, requests information on the key newTestDoc, contained in the administrator-created collection MyCollection; which is in the administrator-created scope MyScope, in the travel-sample bucket.

    /opt/couchbase/bin/cbstats -u Administrator -p password \
    -b travel-sample localhost:11210 \
    key 'newTestDoc' 4 MyScope.MyCollection

    The response is as follows:

    key newTestDoc 4 MyScope.MyCollection
    stats for key newTestDoc
     key_cas:         1602139598762409984
     key_exptime:     0
     key_flags:       100663298
     key_is_dirty:    false
     key_is_resident: true
     key_vb_state:    active

    Get Key Information, Specifying Collection ID

    The following example requests information on the key airline_10, which is provided by default in the sample bucket travel-sample. The call uses the id <collectionID> option, to specify that the default collection should be searched:

    /opt/couchbase/bin/cbstats -u Administrator -p password \
    -b travel-sample localhost:11210 \
    key 'airline_10' 361 id 0x0

    The response is as follows:

    key-byid airline_10 361 0x0
    stats for key airline_10
     key_cas:         1601426228785053696
     key_exptime:     0
     key_flags:       100663298
     key_is_dirty:    false
     key_is_resident: true
     key_vb_state:    active

    The following example, again using the id <collectionID> option, requests information on the key newTestDoc, contained in the administrator-created collection MyCollection, in the travel-sample bucket.

    /opt/couchbase/bin/cbstats -u Administrator -p password \
    -b travel-sample localhost:11210 \
    key 'newTestDoc' 4 id 0x9

    The response is as follows:

    key-byid newTestDoc 4 0x9
    stats for key newTestDoc
     key_cas:         1602139598762409984
     key_exptime:     0
     key_flags:       100663298
     key_is_dirty:    false
     key_is_resident: true
     key_vb_state:    active

    See Also

    For an overview of scopes and collections, see Scopes and Collections. To use cbstats to provide information on collections, see the reference page for the cbstats collections command. For information on providing verification of keys, see the reference page for the cbstats vkey command.