It’s a lot easier to think of what a directory is useful for rather than to state what it is. Directories are a powerful and efficient way to group documents in a database. While collections are also powerful and efficient, directories have always seemed more natural because they have an obvious analog in filesystem directories and because they can effectively be serialized through the document URI.
Like documents, directories can have properties. You may have run into this while performing bulk loads as the server tries to keep the last modified date for the directory reflective of the most recent children documents. You can also put your own properties on the directory, which can be quite handy for assigning properties that are common to a group of documents.
Like documents, directories have permissions. You can control the documents users can “see” through webdav by controlling access at the directory level, and you can also assign a default permission level on a directory that all of its children documents will inherit. This is especially useful if you are using permissions on your stored modules and editing them – you can simply load with the appropriate URI, and all the right permissions will be assigned at load time.
Directories seem like documents in some regards but, when you create a directory in MarkLogic, it is reported by the database status screen as a fragment rather than a document. Furthermore, input() and doc() do not return directories, they only return document nodes. You could have a million directories in the database and doc() will return an empty sequence.
The properties of a directory at a URI will identify itself as a directory. For example, the properties of the root directory xdmp:document-properties("/") will report
You can see how many directories you have by executing
You can list all the directory URIs in the database by executing
for $uri-prop in xdmp:document-properties(cts:uris())[.//prop:directory] return base-uri($uri-prop)
If the database is configured to create directories automatically then a document is insert will result in directories being created if they do not already exists (based on the URI of the document).
|Warning: automatic directory creation has a performance penalty as document insert causes additional write locks to be acquired for all directories implied by the URI; This may have the effect of serializing inserts. Unless there is a need to have automatic directory creation turned on (such as for webdav), it is recommended that the directory creation setting on the databases be set to manual.
You can manually create a directory by calling
xdmp:directory-create( $uri )
WARNING: xdmp:directory-delete( $uri ) deletes not only the directory, but also deletes all of its child and descendant documents and directories from the database.
Use caution when calling this function. Bulk delete calls like xdmp:directory-delete and xdmp:collection-delete delete the relevant documents' term lists without knowledge of those documents URIs. Without the URIs, the server can't determine the mimetypes of the corresponding documents. Without the mimetypes, it cannot prove that the corresponding documents are or are not modules. Since the server doesn't know if modules are being deleted, module caches will consequently always be invalidated when calling bulk delete calls like xdmp:directory-delete and xdmp:collection-delete, regardless of the contents of either the relevant directory or collection. If your application requests cannot afford the response time impact of module cache re-warming, you should instead call xdmp:document-delete for each document in the relevant directory or collection instead of calling bulk delete operations like xdmp:directory-delete and xdmp:collection-delete.
If all you want to do is delete a directory fragment, you need to just remove the node from it's property.
xdmp:node-delete(xdmp:document-properties( $uri ));