MarkLogic 12 EA 1 Product Documentation
xdmp.forestStatus

xdmp.forestStatus(
   forest-id as (Number|String)[],
   [options as String[]]
) as Sequence

Summary

Returns the status of a forest as a Sequence of ObjectNodes.

Parameters

forest-id One or more forest IDs.

Parameters
forest-id	One or more forest IDs.
options	Options include: `memorySummary` Summary of memory consumption for the stand. `memoryDetail` Detailed memory consumption information for the stand including memory summary, every range index ID (see specification with `xdmp.databaseDescribeIndexes`) and its memory consumption in bytes.

options

Options include:

memorySummary: Summary of memory consumption for the stand.
memoryDetail: Detailed memory consumption information for the stand including memory summary, every range index ID (see specification with xdmp.databaseDescribeIndexes) and its memory consumption in bytes.

Required Privileges

http://marklogic.com/xdmp/privileges/status

Usage Notes

The structure of the data returned is as follows:

forestId

The unique key of the forest.

forestName

The forest name.

hostId

The unique key of the host that mounts the forest

state

The state of the forest.

stateDetail

Additional details on why a forest is in a particular state.

enabled

Is the forest enabled or not.

availability

Availability of forests data.

encryption

Forest encryption setting

updatesAllowed

The types of updates allowed on the forest.

rebalancerEnable

Is the rebalancer on this forest enabled or not.

lowerBound

The lower bound of the range on the forest.

upperBound

The upper bound of the range on the forest.

masterForest

replicaForests

The replica forests.

This is an object with the following properties:

replicaForest

currentMasterForest

currentMasterPreciseTime

currentMasterFsn

currentForeignMasterCluster

currentForeignMasterDatabase

currentForeignMasterForest

currentForeignMasterPreciseTime

currentForeignMasterFsn

error

The error in processing forest status.

rebalancerError

The error in rebalancing.

databaseId

The database the forest belongs to.

lastStateChange

The last time the forest state changed.

nonblockingTimestamp

The most current timestamp for which a query will execute without waiting for transactions to settle.

maxQueryTimestamp

The largest timestamp a query has run at.

timestampTable

Table of blocked timestamps.

This is an object with the following properties:

timestampEntry

Blocked timestamp.

This is an object with the following properties:

timestamp: Blocked timestamp.
count: The reference count.

numaNode

A NUMA node number.

dataDir

The data directory.

largeDataDir

The large data directory.

fastDataDir

The fast data directory.

journalsSize

The amount of space the journals take up on disk.

largeDataSize

The amount of space large objects take up on disk.

orphanedBinaries

The count of orphaned large binaries.

stands

The stands in the forest.

This is an object with the following properties:

stand

The stand of a forest.

This is an object with the following properties:

standId

The unique key of a stand.

path

The path of the stand.

standKind

The kind of stand.

isFast

Is the stand in the fast data directory ?

labelVersion

The version number of the label file.

diskSize

The amount of space the stand takes on disk.

encryptedDiskSize

The amount of space the stand has encrypted on disk.

memorySize

The amount of space the stand takes in memory.

memorySummary

The list of memory consumption in bytes for this stand.

This is an object with the following properties:

compressedTreeStorageBytes
listStorageBytes
frequenciesFileBytes
listFileBytes
stopKeySetFileBytes
treeFileBytes
linkKeysIndexBytes
uniqueKeysIndexBytes
uriKeysIndexBytes
binaryKeysFileBytes
linkKeysFileBytes
ordinalsFileBytes
qualitiesFileBytes
timeStampsFileBytes
uniqueKeysFileBytes
uriKeysFileBytes
lengthsFileBytes
reverseIndexBytes
tripleIndexBytes
geospatialRegionIndexesBytes
rangeIndexesBytes

memoryDetail

Memory consumption in bytes for Geospatial region and Range indexes.

This is an object with the following properties:

memoryGeospatialRegion

The list of memory consumption in bytes for Geospatial region.

This is an object with the following properties:

regionStorageBytes
sliceStorageBytes
floatRtreeNodePoolBytes
doubleRtreeNodePoolBytes
floatGeoHashAtlasBytes
doubleGeoHashAtlasBytes

memoryRangeIndexes

Memory consumption in bytes for string storage and all range indexes.

This is an object with the following properties:

stringStorageBytes

String storage in bytes for all range indexes in memory.

index

Range indexes in memory. The range index types include Range element, Range element attribute, Range field, Range path, Geospatial path, Geospatial element, Geospatial element child, Geospatial element pair, Geospatial element attribute pair, URI lexicon (system default), Collection lexicon (system default).

This is an object with the following properties:

indexId: Index ID of the range index.
indexMemoryBytes: Memory consumption size in byes for the index.
indexOnDiskBytes: The on-disk file size in bytes for the index.

listCacheHits

The number of hits on the list cache.

listCacheMisses

The number of misses on the list cache.

listCacheHitRate

The average number of hits on the list cache.

listCacheMissRate

The average number of misses on the list cache.

compressedTreeCacheHits

The number of hits on the compressed cache.

compressedTreeCacheMisses

The number of misses on the compressed cache.

compressedTreeCacheHitRate

The average number of hits on the compressed cache.

compressedTreeCacheMissRate

The average number of misses on the compressed cache.

tripleCacheHits

The number of hits on the list cache.

tripleCacheMisses

The number of misses on the list cache.

tripleCacheHitRate

The average number of hits on the list cache.

tripleCacheMissRate

The average number of misses on the list cache.

tripleValueCacheHits

The number of hits on the list cache.

tripleValueCacheMisses

The number of misses on the list cache.

tripleValueCacheHitRate

The average number of hits on the list cache.

tripleValueCacheMissRate

The average number of misses on the list cache.

forestReserve

The amount of space needed for merging.

mergeEnable

Is the merge on this forest enabled or not.

currentTime

The current time.

merges

The merges in progress on the forest.

This is an object with the following properties:

merge

The merge of two stands in a forest.

This is an object with the following properties:

mergeId

A unique key for a merge.

canceled

Is a merge canceled or not.

inputStands

The input stands of a merge.

This is an object with the following properties:

standId: The unique key of a stand.

path

The path of the stand.

outputStand

The ID of a stand resulting from a merge.

startTime

The time a merge started.

finalSize

The estimated final size of a stand.

currentSize

The current size of a merging stand.

mergeRate

The rate of a merge (MB/sec).

rebalancing

Is this forest rebalancing.

reindexing

Is this forest reindexing.

deviceSpace

The amount of space left on forest device.

largeDeviceSpace

The amount of space left on large forest device.

fastDeviceSpace

The amount of space left on fast forest device.

lastBackup

The last time the forest was backed up.

lastIncrBackup

The last time the forest was incremental backed up.

backups

The backups in progress on the forest.

This is an object with the following properties:

backup

The backup of a forest.

This is an object with the following properties:

path: The path of the stand.
startTime: The time a merge started.
finalSize: The estimated final size of a stand.
currentSize: The current size of a merging stand.
incrementalBackup: Is incremental backup enabled for the backup?
journalArchiving: Is journal archiving enabled for the backup?
journalArchivePath: Path to the associated journal archive location.
journalArchiveLagLimit: Number of seconds the archived journal can lag the active journal.

lastRestore

The last time the forest was restored.

restore

The restore of a forest.

This is an object with the following properties:

path: The path of the stand.
startTime: The time a merge started.
finalSize: The estimated final size of a stand.
currentSize: The current size of a merging stand.
restoreState: The state of the forest restore.
restoreToTime: The date and time this backup was created.
incrementalBackup: Is incremental backup enabled for the backup?
journalArchiving: Is journal archiving enabled for the backup?
journalArchivePath: Path to the associated journal archive location.
safeRestoreToTime: The safest timestamp closest to the restore-to-time at which the forest is in a consistent state.

transactionCoordinators

The set of transactions that this forest is coordinating.

This is an object with the following properties:

transactionCoordinator

A transaction that this forest is coordinating.

This is an object with the following properties:

transactionId

The unique key of the transaction.

decisionState

The state of the transaction.

xa.xid

participants

The set of participating transactions.

This is an object with the following properties:

participant

A participating transaction.

This is an object with the following properties:

participantId: The forest ID of a participant of a transaction.
participantStatus: The state of the participating transaction.

size

The number of bytes taken up in the journal by this in-process transaction information.

transactionParticipants

The set of transactions that this forest is participating in.

This is an object with the following properties:

transactionParticipant

A transaction that this forest is participating in.

This is an object with the following properties:

transactionId: The unique key of the transaction.
coordinatorId: The forest ID of the coordinator of a transaction.
minCommitTimestamp: The minimum commit timestamp for the transaction.
size: The number of bytes taken up in the journal by this in-process transaction information.

transactionJournalSize

The number of bytes taken up in the journal by the in-process transactions.

transactionJournalLimit

The maximum number of bytes that can be taken up in the journal by the in-process transactions.

queryReadBytes

The number of bytes read off disk.

queryReadTime

The time (as xs:dayTimeDuration) to read query data from disk.

queryReadRate

The moving average of throughput reading query data from disk, in megabytes per second.

queryReadLoad

Disk reading time threads spent for a query in proportion to the elapsed time. This is a moving average summed for all of the contributing threads.

journalWriteBytes

The number of bytes written to the journal on disk.

journalWriteTime

The time (as xs:dayTimeDuration) to write data to the journal.

journalWriteRate

The moving average of writing data to the journal, in megabytes per second.

journalWriteLoad

Journal writing time threads spent in proportion to the elapsed time. This is summed for all of the threads writing on the host.

saveWriteBytes

The number of bytes written when saving in-memory stands.

saveWriteTime

The time (as xs:dayTimeDuration) spent saving in-memory stands.

saveWriteRate

The moving average of writing data to in-memory stands, in megabytes per second.

saveWriteLoad

The moving average of time threads spent writing to in-memory stands, in proportion to the elapsed time. This is summed for all of the threads writing on the host.

mergeReadBytes

The number of bytes read during merges.

mergeReadTime

The time (as xs:dayTimeDuration) to read data for merges.

mergeReadRate

The moving average throughput of reading merge data from disk, in megabytes per second.

mergeReadLoad

Disk read time threads spent during merge, in proportion to the elapsed time. This is summed for all of the contributing threads.

mergeWriteBytes

The number of bytes written to disk for merges.

mergeWriteTime

The time (as xs:dayTimeDuration) to write data for merges.

mergeWriteRate

The moving average throughput of writing data for merges, in megabytes per second.

mergeWriteLoad

Disk writing time threads spent for merges, in proportion to the elapsed time. This is summed for all of the threads writing on the host.

backupReadBytes

The number of bytes read from disk for backups.

backupReadTime

Thee time (as xs:dayTimeDuration) to read data for backups.

backupReadRate

The moving average throughput of reading backup data from disk, in megabytes per second.

backupReadLoad

Disk read time threads spent for backup, in proportion to the elapsed time. This is summed for all of the contributing threads.

backupWriteBytes

The number of bytes written to disk for backups.

backupWriteTime

The time (as xs:dayTimeDuration) to write data to backups.

backupWriteRate

The moving average throughput of writing data for backups, in megabytes per second.

backupWriteLoad

Disk writing time threads spent for backups, in proportion to the elapsed time. This is summed for all of the threads writing on the host.

restoreReadBytes

The number of bytes read from disk for restores.

restoreReadTime

The time (as xs:dayTimeDuration) to read data for restores.

restoreReadRate

The moving average throughput of reading restore data from disk, in megabytes per second.

restoreReadLoad

Disk read time threads spent for restores, in proportion to the elapsed time. This is summed for all of the contributing threads.

restoreWriteBytes

The number of bytes written to disk for restores.

restoreWriteTime

The time (as xs:dayTimeDuration) to write data for restores.

restoreWriteRate

The moving average throughput of writing data for restores, in megabytes per second.

restoreWriteLoad

Disk write time threads spent for restores, in proportion to the elasped time. This is summed for all of the threads writing on the host.

largeReadBytes

The number of bytes read from large documents.

largeReadTime

The time (as xs:dayTimeDuration) to read data from large documents.

largeReadRate

The moving average throughput of reading large documents from disk, in megabytes per second.

largeReadLoad

Disk read time threads spent on large documents, in proportion to the elapsed time.

largeWriteBytes

The number of bytes written to disk for large documents.

largeWriteTime

The time (as xs:dayTimeDuration) to write data for large documents.

largeWriteRate

The moving average throughput of writing data for large documents, in megabytes per second.

largeWriteLoad

Disk write time threads spent for large documents, in proportion to the elapsed time.

databaseReplicationReceiveBytes

The number of bytes received for database replication.

databaseReplicationReceiveTime

The time (as xs:dayTimeDuration) to receive data for database replication.

databaseReplicationReceiveRate

The moving average throughput of receiving data for database replication, in megabytes per second.

databaseReplicationReceiveLoad

Time threads spent receiving data for database replication, in proportion to the elapsed time.

databaseReplicationSendBytes

The number of bytes sent for database replication.

databaseReplicationSendTime

The time (as xs:dayTimeDuration) to send data for database replication.

databaseReplicationSendRate

The moving average throughput of sending data for database replication, in megabytes per second.

databaseReplicationSendLoad

Time threads spent sending data for database replication, in proportion to the elapsed time.

readLockCount

The total number of read locks, summed across all forests on the host.

readLockWaitTime

The total time spent waiting for read locks, summed across all forests on the host.

readLockHoldTime

The total time spent holding read locks, summed across all forests on the host.

readLockRate

The rate of read lock acquistions, summed across all forests on the host.

readLockWaitLoad

Time threads spent waiting to acquire read locks in proportion to the elasped time, summed across all forests on the host.

readLockHoldLoad

Time threads spent holding read locks in proportion to the elapsed time, summed across all forests on the host.

writeLockCount

The total number of write lock acquistions, summed across all forests on the host.

writeLockWaitTime

The total time spent waiting for write locks, summed across all forests on the host.

writeLockHoldTime

The total time spent holding write locks, summed across all forests on the host.

writeLockRate

The rate of write lock acquistions, summed across all forests on the host.

writeLockWaitLoad

Time threads spent waiting to acquire write locks in proportion to the elapsed time, summed across all forests on the host.

writeLockHoldLoad

Time threads spent holding write locks in proportion to the elapsed time, summed across all forests on the host.

deadlockCount

The number of deadlocks, summed across all forests on the host.

deadlockWaitTime

The total time spent waiting for locks that eventually deadlocked, summed across all forests on the host.

deadlockRate

The rate of deadlock occurrances, summed across all forests on the host.

deadlockWaitLoad

Time threads spent waiting for locks that eventually result in deadlocks in proportion to the elasped time, summed across all forests on the host.

largeBinaryCacheHits

The number of hits on the large binary cache.

largeBinaryCacheMisses

The number of misses on the large binary cache.

largeBinaryCacheHitRate

The average number of hits on the large binary cache.

largeBinaryCacheMissRate

The average number of misses on the large binary cache.

replication

This is an object with the following properties:

foreignMaster

Information about the foreign master.

This is an object with the following properties:

foreignClusterId: The ID of the foreign cluster.
foreignDatabaseId: The ID of the foreign database.
foreignForestId: The ID of the foreign forest.
foreignPreciseTime: The precise time of the foreign cluster.
foreignFsn: The frame fsn number from the foreign database.

foreignReplicas

Information about foreign replicas.

This is an object with the following properties:

foreignReplica

Information about a particular foreign replica.

This is an object with the following properties:

foreignClusterId: The ID of the foreign cluster.
foreignDatabaseId: The ID of the foreign database.
foreignForestId: The ID of the foreign forest.
replicationEnabled: Is database replication enabled or not.
lagLimit: The lag limit.
pendingFrames: The number of pending frames.
pendingBytes: The number of bytes for pending frames.
pendingLag: The time of the pending lag limit.
sendBytes: The number of bytes sent for database replication.
sendTime: The time (as xs:dayTimeDuration) to send data for database replication.
sendRate: The moving average throughput of sending data for database replication, in megabytes per second.
sendLoad: Time threads spent sending data for database replication, in proportion to the elapsed time.
suspended: Is database replication suspended or not.

pointInTimeRecovery

Information about point in time recovery.

This is an object with the following properties:

journalArchive

Information about the journal archive.

This is an object with the following properties:

path: The path of the stand.
lagLimit: The lag limit.
pendingFrames: The number of pending frames.
pendingBytes: The number of bytes for pending frames.
pendingLag: The time of the pending lag limit.

unclosedStands

The unclosed stands in the forest.

This is an object with the following properties:

unclosedStand

The unclosed stand of a forest.

This is an object with the following properties:

standId

The unique key of a stand.

path

The path of the stand.

diskSize

The amount of space the stand takes on disk.

memorySize

The amount of space the stand takes in memory.

reference

The reference to an unclosed forest stand.

This is an object with the following properties:

count: The reference count.
earliest: The earliest refrence time.
latest: The latest refrence time.
frame: A stack frame.

forestValueRange

Value range of a range index

This is an object with the following properties:

cts.baseReference
cts.range

fragmentCount

The total number of fragments for a given reindexing or rebalancing activity.

dataSize

The amount of space forest data files take up on disk.

Example

xdmp.forestStatus(
  xdmp.databaseForests(
    xdmp.database("Documents")));
=>
{
   "forestId":"3199975194245760821",
   "forestName":"Documents",
   "hostId":"16691872130013704340",
   "state":"open",
   "enabled":true,
   "availability":"online",
   "updatesAllowed":"all",
   "rebalancerEnable":true,
   "lowerBound":"1",
   "upperBound":"100",
   "masterForest":"3199975194245760821",
   "replicaForests":[
   ],
   "currentMasterForest":"3199975194245760821",
   "currentMasterPreciseTime":"2014-11-24T16:58:05.766563-08:00",
   "currentMasterFsn":144,
   "databaseId":"1137197755037514772",
   "lastStateChange":"2014-11-25T18:13:16.300032-08:00",
   "nonblockingTimestamp":"14169680666077180",
   "dataDir":"/space/trunk-xdmp/src/Data",
   "journalsSize":0,
   "largeDataSize":0,
   "orphanedBinaries":0,
   "stands":[
      {
         "standId":"6976269206355638804",
         "path":"/space/trunk-xdmp/src/Data/Forests/Documents/00000002",
         "standKind":"Active",
         "isFast":false,
         "labelVersion":50397184,
         "diskSize":0,
         "memorySize":1,
         "listCacheHits":122,
         "listCacheMisses":308,
         "listCacheHitRate":0.0244068801403046,
         "listCacheMissRate":0.0506149381399155,
         "compressedTreeCacheHits":0,
         "compressedTreeCacheMisses":0,
         "compressedTreeCacheHitRate":0,
         "compressedTreeCacheMissRate":0,
         "tripleCacheHits":0,
         "tripleCacheMisses":0,
         "tripleCacheHitRate":0,
         "tripleCacheMissRate":0,
         "tripleValueCacheHits":0,
         "tripleValueCacheMisses":0,
         "tripleValueCacheHitRate":0,
         "tripleValueCacheMissRate":0
      }
   ],
   "forestReserve":0,
   "currentTime":"2014-11-25T18:14:53.211604-08:00",
   "merges":[
   ],
   "rebalancing":false,
   "reindexing":false,
   "deviceSpace":223489,
   "backups":[
   ],
   "transactionCoordinators":[
   ],
   "transactionParticipants":[
   ],
   "transactionJournalSize":0,
   "transactionJournalLimit":134152192,
   "queryReadBytes":17360,
   "queryReadTime":"PT0.000046S",
   "queryReadRate":0,
   "queryReadLoad":0,
   "journalWriteBytes":0,
   "journalWriteTime":"PT0S",
   "journalWriteRate":0,
   "journalWriteLoad":0,
   "saveWriteBytes":0,
   "saveWriteTime":"PT0S",
   "saveWriteRate":0,
   "saveWriteLoad":0,
   "mergeReadBytes":0,
   "mergeReadTime":"PT0S",
   "mergeReadRate":0,
   "mergeReadLoad":0,
   "mergeWriteBytes":0,
   "mergeWriteTime":"PT0S",
   "mergeWriteRate":0,
   "mergeWriteLoad":0,
   "backupReadBytes":0,
   "backupReadTime":"PT0S",
   "backupReadRate":0,
   "backupReadLoad":0,
   "backupWriteBytes":0,
   "backupWriteTime":"PT0S",
   "backupWriteRate":0,
   "backupWriteLoad":0,
   "restoreReadBytes":0,
   "restoreReadTime":"PT0S",
   "restoreReadRate":0,
   "restoreReadLoad":0,
   "restoreWriteBytes":0,
   "restoreWriteTime":"PT0S",
   "restoreWriteRate":0,
   "restoreWriteLoad":0,
   "largeReadBytes":0,
   "largeReadTime":"PT0S",
   "largeReadRate":0,
   "largeReadLoad":0,
   "largeWriteBytes":0,
   "largeWriteTime":"PT0S",
   "largeWriteRate":0,
   "largeWriteLoad":0,
   "databaseReplicationReceiveBytes":0,
   "databaseReplicationReceiveTime":"PT0S",
   "databaseReplicationReceiveRate":0,
   "databaseReplicationReceiveLoad":0,
   "databaseReplicationSendBytes":0,
   "databaseReplicationSendTime":"PT0S",
   "databaseReplicationSendRate":0,
   "databaseReplicationSendLoad":0,
   "readLockCount":0,
   "readLockWaitTime":"PT0S",
   "readLockHoldTime":"PT0S",
   "readLockRate":0,
   "readLockWaitLoad":0,
   "readLockHoldLoad":0,
   "writeLockCount":0,
   "writeLockWaitTime":"PT0S",
   "writeLockHoldTime":"PT0S",
   "writeLockRate":0,
   "writeLockWaitLoad":0,
   "writeLockHoldLoad":0,
   "deadlockCount":0,
   "deadlockWaitTime":"PT0S",
   "deadlockRate":0,
   "deadlockWaitLoad":0,
   "largeBinaryCacheHits":0,
   "largeBinaryCacheMisses":0,
   "largeBinaryCacheHitRate":0,
   "largeBinaryCacheMissRate":0
   "externalKMSRequestTime": 0,
   "externalKMSRequestRate": 0,
   "currentExternalKMSHost": "safenet150v-3.marklogic.com"
}
//----------------
{
   "forestId":"9838038749549278946",
   "forestName":"forest1",
   "hostId":"16691872130013704340",
   "state":"unmounted",
   "enabled":true,
   "availability":"offline",
   "databaseId":"1137197755037514772",
   "fragmentCount":99,
   "dataSize":15,
   "forestValueRange":{
      "elementReference":{
         "namespaceURI":"",
         "localname":"longfield",
         "scalarType":"long",
         "nullable":true
      }
   },
   "range":{
      "minimum":{
         "type":"long",
         "value":"1"
      },
      "maximum":{
         "type":"long",
         "value":"99"
      },
      "lowerBound":{
         "type":"long",
         "value":"1"
      },
      "upperBound":{
         "type":"long",
         "value":"100"
      }
   }
}

Example

xdmp.forestStatus((xdmp.forest("test01")),("memorySummary"));

=>
{
"forestId": "9661955269470222725",
"forestName": "test01",
"hostId": "2757765848124305372",
...
"stands": [
{
"standId": "11638115280016928621",
"path": "/space/xdmp101/src/Data/Forests/test01/00000003",
...
"memorySize": 1,
"memorySummary": {
"frequenciesFileBytes": 1952,
"listFileBytes": 304,
"stopKeySetFileBytes": 0,
"treeFileBytes": 128,
"linkKeyIndexBytes": 0,
"uniqueKeyIndexBytes": 12296,
"uriKeyIndexBytes": 12296,
"binaryKeysFileBytes": 0,
"linkKeysFileBytes": 320,
"ordinalsFileBytes": 320,
"qualitiesFileBytes": 160,
"timestampsFileBytes": 640,
"uniqKeysFileBytes": 320,
"uriKeysFileBytes": 320,
"reverseIndexBytes": 0,
"tripleIndexBytes": 56,
"geoSpatialRegionIndexesBytes": 0,
"rangeIndexesBytes": 2797
}
,
"listCacheHits": 578,
"listCacheMisses": 456,
...
}

MarkLogic 12 EA 1 Product Documentationxdmp.forestStatus

Summary

Required Privileges

Usage Notes

Example

Example

MarkLogic 12 EA 1 Product Documentation
xdmp.forestStatus