MarkLogic 12 EA 2 Product Documentation

xdmp:forest-status

xdmp:forest-status(
   $forest-id as xs:unsignedLong*,
   [$options as xs:string*]
) as element(forest-status)*

Summary

Returns the status of a forest.

Required Privileges

Usage Notes

The structure of the data returned is as follows:

forest-id

The unique key of the forest.

forest-name

The forest name.

host-id

The unique key of the host that mounts the forest

state

The state of the forest.

state-detail

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

updates-allowed

The types of updates allowed on the forest.

rebalancer-enable

Is the rebalancer on this forest enabled or not.

lower-bound

The lower bound of the range on the forest.

upper-bound

The upper bound of the range on the forest.

master-forest

replica-forests

The replica forests.

This is a complex element with the following element children:

replica-forest

current-master-forest

current-master-precise-time

current-master-fsn

current-foreign-master-cluster

current-foreign-master-database

current-foreign-master-forest

current-foreign-master-precise-time

current-foreign-master-fsn

error

The error in processing forest status.

rebalancer-error

The error in rebalancing.

database-id

The database the forest belongs to.

last-state-change

The last time the forest state changed.

nonblocking-timestamp

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

max-query-timestamp

The largest timestamp a query has run at.

timestamp-table

Table of blocked timestamps.

This is a complex element with the following element children:

timestamp-entry

Blocked timestamp.

This is a complex element with the following element children:

timestamp

Blocked timestamp.

count

The reference count.

numa-node

A NUMA node number.

data-dir

The data directory.

large-data-dir

The large data directory.

fast-data-dir

The fast data directory.

journals-size

The amount of space the journals take up on disk.

large-data-size

The amount of space large objects take up on disk.

orphaned-binaries

The count of orphaned large binaries.

stands

The stands in the forest.

This is a complex element with the following element children:

stand

The stand of a forest.

This is a complex element with the following element children:

stand-id

The unique key of a stand.

path

The path of the stand.

stand-kind

The kind of stand.

is-fast

Is the stand in the fast data directory ?

label-version

The version number of the label file.

disk-size

The amount of space the stand takes on disk.

encrypted-disk-size

The amount of space the stand has encrypted on disk.

memory-size

The amount of space the stand takes in memory.

memory-summary

The list of memory consumption in bytes for this stand.

This is a complex element with the following element children:

compressed-tree-storage-bytes

list-storage-bytes

frequencies-file-bytes

list-file-bytes

stop-key-set-file-bytes

tree-file-bytes

link-keys-index-bytes

unique-keys-index-bytes

uri-keys-index-bytes

binary-keys-file-bytes

link-keys-file-bytes

ordinals-file-bytes

qualities-file-bytes

time-stamps-file-bytes

unique-keys-file-bytes

uri-keys-file-bytes

lengths-file-bytes

reverse-index-bytes

triple-index-bytes

geospatial-region-indexes-bytes

range-indexes-bytes

memory-detail

Memory consumption in bytes for Geospatial region and Range indexes.

This is a complex element with the following element children:

memory-geospatial-region

The list of memory consumption in bytes for Geospatial region.

This is a complex element with the following element children:

region-storage-bytes

slice-storage-bytes

float-rtree-node-pool-bytes

double-rtree-node-pool-bytes

float-geo-hash-atlas-bytes

double-geo-hash-atlas-bytes

memory-range-indexes

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

This is a complex element with the following element children:

string-storage-bytes

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 a complex element with the following element children:

index-id

Index ID of the range index.

index-memory-bytes

Memory consumption size in byes for the index.

index-on-disk-bytes

The on-disk file size in bytes for the index.

list-cache-hits

The number of hits on the list cache.

list-cache-misses

The number of misses on the list cache.

list-cache-hit-rate

The average number of hits on the list cache.

list-cache-miss-rate

The average number of misses on the list cache.

compressed-tree-cache-hits

The number of hits on the compressed cache.

compressed-tree-cache-misses

The number of misses on the compressed cache.

compressed-tree-cache-hit-rate

The average number of hits on the compressed cache.

compressed-tree-cache-miss-rate

The average number of misses on the compressed cache.

triple-cache-hits

The number of hits on the list cache.

triple-cache-misses

The number of misses on the list cache.

triple-cache-hit-rate

The average number of hits on the list cache.

triple-cache-miss-rate

The average number of misses on the list cache.

triple-value-cache-hits

The number of hits on the list cache.

triple-value-cache-misses

The number of misses on the list cache.

triple-value-cache-hit-rate

The average number of hits on the list cache.

triple-value-cache-miss-rate

The average number of misses on the list cache.

forest-reserve

The amount of space needed for merging.

merge-enable

Is the merge on this forest enabled or not.

current-time

The current time.

merges

The merges in progress on the forest.

This is a complex element with the following element children:

merge

The merge of two stands in a forest.

This is a complex element with the following element children:

merge-id

A unique key for a merge.

canceled

Is a merge canceled or not.

input-stands

The input stands of a merge.

This is a complex element with the following element children:

stand-id

The unique key of a stand.

path

The path of the stand.

output-stand

The ID of a stand resulting from a merge.

start-time

The time a merge started.

final-size

The estimated final size of a stand.

current-size

The current size of a merging stand.

merge-rate

The rate of a merge (MB/sec).

rebalancing

Is this forest rebalancing.

reindexing

Is this forest reindexing.

device-space

The amount of space left on forest device.

large-device-space

The amount of space left on large forest device.

fast-device-space

The amount of space left on fast forest device.

last-backup

The last time the forest was backed up.

last-incr-backup

The last time the forest was incremental backed up.

backups

The backups in progress on the forest.

This is a complex element with the following element children:

backup

The backup of a forest.

This is a complex element with the following element children:

path

The path of the stand.

start-time

The time a merge started.

final-size

The estimated final size of a stand.

current-size

The current size of a merging stand.

incremental-backup

Is incremental backup enabled for the backup?

journal-archiving

Is journal archiving enabled for the backup?

journal-archive-path

Path to the associated journal archive location.

journal-archive-lag-limit

Number of seconds the archived journal can lag the active journal.

last-restore

The last time the forest was restored.

restore

The restore of a forest.

This is a complex element with the following element children:

path

The path of the stand.

start-time

The time a merge started.

final-size

The estimated final size of a stand.

current-size

The current size of a merging stand.

restore-state

The state of the forest restore.

restore-to-time

The date and time this backup was created.

incremental-backup

Is incremental backup enabled for the backup?

journal-archiving

Is journal archiving enabled for the backup?

journal-archive-path

Path to the associated journal archive location.

safe-restore-to-time

The safest timestamp closest to the restore-to-time at which the forest is in a consistent state.

transaction-coordinators

The set of transactions that this forest is coordinating.

This is a complex element with the following element children:

transaction-coordinator

A transaction that this forest is coordinating.

This is a complex element with the following element children:

transaction-id

The unique key of the transaction.

decision-state

The state of the transaction.

xa:xid

participants

The set of participating transactions.

This is a complex element with the following element children:

participant

A participating transaction.

This is a complex element with the following element children:

participant-id

The forest ID of a participant of a transaction.

participant-status

The state of the participating transaction.

size

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

transaction-participants

The set of transactions that this forest is participating in.

This is a complex element with the following element children:

transaction-participant

A transaction that this forest is participating in.

This is a complex element with the following element children:

transaction-id

The unique key of the transaction.

coordinator-id

The forest ID of the coordinator of a transaction.

min-commit-timestamp

The minimum commit timestamp for the transaction.

size

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

transaction-journal-size

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

transaction-journal-limit

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

query-read-bytes

The number of bytes read off disk.

query-read-time

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

query-read-rate

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

query-read-load

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.

journal-write-bytes

The number of bytes written to the journal on disk.

journal-write-time

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

journal-write-rate

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

journal-write-load

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

save-write-bytes

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

save-write-time

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

save-write-rate

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

save-write-load

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.

merge-read-bytes

The number of bytes read during merges.

merge-read-time

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

merge-read-rate

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

merge-read-load

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

merge-write-bytes

The number of bytes written to disk for merges.

merge-write-time

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

merge-write-rate

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

merge-write-load

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.

backup-read-bytes

The number of bytes read from disk for backups.

backup-read-time

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

backup-read-rate

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

backup-read-load

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

backup-write-bytes

The number of bytes written to disk for backups.

backup-write-time

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

backup-write-rate

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

backup-write-load

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.

restore-read-bytes

The number of bytes read from disk for restores.

restore-read-time

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

restore-read-rate

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

restore-read-load

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

restore-write-bytes

The number of bytes written to disk for restores.

restore-write-time

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

restore-write-rate

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

restore-write-load

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.

large-read-bytes

The number of bytes read from large documents.

large-read-time

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

large-read-rate

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

large-read-load

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

large-write-bytes

The number of bytes written to disk for large documents.

large-write-time

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

large-write-rate

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

large-write-load

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

database-replication-receive-bytes

The number of bytes received for database replication.

database-replication-receive-time

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

database-replication-receive-rate

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

database-replication-receive-load

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

database-replication-send-bytes

The number of bytes sent for database replication.

database-replication-send-time

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

database-replication-send-rate

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

database-replication-send-load

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

read-lock-count

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

read-lock-wait-time

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

read-lock-hold-time

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

read-lock-rate

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

read-lock-wait-load

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

read-lock-hold-load

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

write-lock-count

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

write-lock-wait-time

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

write-lock-hold-time

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

write-lock-rate

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

write-lock-wait-load

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

write-lock-hold-load

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

deadlock-count

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

deadlock-wait-time

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

deadlock-rate

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

deadlock-wait-load

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

large-binary-cache-hits

The number of hits on the large binary cache.

large-binary-cache-misses

The number of misses on the large binary cache.

large-binary-cache-hit-rate

The average number of hits on the large binary cache.

large-binary-cache-miss-rate

The average number of misses on the large binary cache.

replication

This is a complex element with the following element children:

foreign-master

Information about the foreign master.

This is a complex element with the following element children:

foreign-cluster-id

The ID of the foreign cluster.

foreign-database-id

The ID of the foreign database.

foreign-forest-id

The ID of the foreign forest.

foreign-precise-time

The precise time of the foreign cluster.

foreign-fsn

The frame fsn number from the foreign database.

foreign-replicas

Information about foreign replicas.

This is a complex element with the following element children:

foreign-replica

Information about a particular foreign replica.

This is a complex element with the following element children:

foreign-cluster-id

The ID of the foreign cluster.

foreign-database-id

The ID of the foreign database.

foreign-forest-id

The ID of the foreign forest.

replication-enabled

Is database replication enabled or not.

lag-limit

The lag limit.

pending-frames

The number of pending frames.

pending-bytes

The number of bytes for pending frames.

pending-lag

The time of the pending lag limit.

send-bytes

The number of bytes sent for database replication.

send-time

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

send-rate

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

send-load

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

suspended

Is database replication suspended or not.

point-in-time-recovery

Information about point in time recovery.

This is a complex element with the following element children:

journal-archive

Information about the journal archive.

This is a complex element with the following element children:

path

The path of the stand.

lag-limit

The lag limit.

pending-frames

The number of pending frames.

pending-bytes

The number of bytes for pending frames.

pending-lag

The time of the pending lag limit.

unclosed-stands

The unclosed stands in the forest.

This is a complex element with the following element children:

unclosed-stand

The unclosed stand of a forest.

This is a complex element with the following element children:

stand-id

The unique key of a stand.

path

The path of the stand.

disk-size

The amount of space the stand takes on disk.

memory-size

The amount of space the stand takes in memory.

reference

The reference to an unclosed forest stand.

This is a complex element with the following element children:

count

The reference count.

earliest

The earliest refrence time.

latest

The latest refrence time.

frame

A stack frame.

forest-value-range

Value range of a range index

This is a complex element with the following element children:

cts:base-reference

cts:range

fragment-count

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

data-size

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

Example

xdmp:forest-status(xdmp:forest("Documents"))
=>
<forest-status xmlns="http://marklogic.com/xdmp/status/forest">
  <forest-id>12434840716430044697</forest-id>
  <forest-name>Documents</forest-name>
  <state>open</state>
  <host-id>13264574555735898770</host-id>
  <database-id>2634450243966805432</database-id>
  <last-state-change>2007-02-16T18:39:31.267-08:00</last-state-change>
  <journals-size>57</journals-size>
  <stands>
    <stand>
      <stand-id>15174447282968484759</stand-id>
      <path>c:\Program Files\MarkLogic\Data\Forests\Documents\00000016</path>
      <stand-kind>Active</stand-kind>
      <label-version>50397184</label-version>
      <disk-size>11</disk-size>
      <memory-size>1</memory-size>
      <list-cache-hits>158</list-cache-hits>
      <list-cache-misses>105</list-cache-misses>
      <list-cache-hit-rate>0</list-cache-hit-rate>
      <list-cache-miss-rate>0</list-cache-miss-rate>
      <compressed-tree-cache-hits>0</compressed-tree-cache-hits>
      <compressed-tree-cache-misses>0</compressed-tree-cache-misses>
      <compressed-tree-cache-hit-rate>0</compressed-tree-cache-hit-rate>
      <compressed-tree-cache-miss-rate>0</compressed-tree-cache-miss-rate>
    </stand>
  </stands>
  <current-time>2007-02-16T18:44:06.154-08:00</current-time>
  <merges/>
  <reindexing>false</reindexing>
  <device-space>3592</device-space>
  <backups/>
  <transaction-coordinators/>
  <transaction-participants/>
</forest-status>

Example

xquery version "1.0-ml";

xdmp:forest-status(xdmp:forest("forestTest"),"memory-detail");
=>
<forest-status xmlns="http://marklogic.com/xdmp/status/forest">
...
<stand>
    <stand-id>4644002137027109170</stand-id>
    <path>/var/opt/MarkLogic/Forests/memory-F1/00000003</path>
    ...
    <disk-size>250</disk-size>
    <encrypted-disk-size>0</encrypted-disk-size>
    <memory-size>34</memory-size>
    <memory-summary>
        <ordinals-file-bytes>2359224</ordinals-file-bytes>
        <qualities-file-bytes>1179612</qualities-file-bytes>
        <link-keys-file-bytes>2359224</link-keys-file-bytes>
        <unique-keys-file-bytes>2359224</unique-keys-file-bytes>
        <uri-keys-file-bytes>2359224</uri-keys-file-bytes>
        <time-stamps-file-bytes>4718448</time-stamps-file-bytes>
        <binary-keys-file-bytes>0</binary-keys-file-bytes>
        ...
        <triple-index-bytes>0</triple-index-bytes>
        <reverse-index-bytes>0</reverse-index-bytes>
        <geospatial-region-indexes-bytes>1622387</geospatial-region-indexes-bytes>
        <range-indexes-bytes>2038704</range-indexes-bytes>
    </memory-summary>
    <memory-detail>
        <memory-geospatial>
            <region-storage-bytes>701736</region-storage-bytes>
            <slice-storage-bytes>724515</slice-storage-bytes>
            <float-rtree-node-pool-bytes>121648</float-rtree-node-pool-bytes>
            <double-rtree-node-pool-bytes>74232</double-rtree-node-pool-bytes>
            <float-geo-hash-atlas-bytes>256</float-geo-hash-atlas-bytes>
            <double-geo-hash-atlas-bytes>0</double-geo-hash-atlas-bytes>
        </memory-geospatial>
        <memory-range-indexes>
            <string-storage-bytes>1776688</string-storage-bytes>
            <index>
                <index-id>203550306667454968</index-id>
                <index-memory-bytes>40408</index-memory-bytes>
            </index>
            <index>
                <index-id>203550306590025653</index-id>
                <index-memory-bytes>4408</index-memory-bytes>
            </index>
            <index>
                <index-id>203550306744884283</index-id>
                <index-memory-bytes>216232</index-memory-bytes>
            </index>
            <index>
                <index-id>8082969983947382622</index-id>
                <index-memory-bytes>88</index-memory-bytes>
            </index>
            ...
        </memory-range-indexes>
    </memory-detail>
    <list-cache-hits>3</list-cache-hits>
    <list-cache-misses>55</list-cache-misses>
    <list-cache-hit-rate>0.001811947</list-cache-hit-rate>
    <list-cache-miss-rate>0.003912835</list-cache-miss-rate>
    ...
    <triple-value-cache-hit-rate>0</triple-value-cache-hit-rate>
    <triple-value-cache-miss-rate>0</triple-value-cache-miss-rate>
</stand>
...
</forest-status>