======Mark Logic Command: put======
Puts a document onto a Mark Logic server.

====Synopsis====
put [options] [file | expression ] ...

====Description====
Puts a file (or expression) from the local system onto a Mark Logic server.


====Options====
||-c,-connect uri||Use the connection string instead of $MLCONNECT||
||-uri uri||Use the specified uri as the uri of the destination document,
Otherwise uses the base uri of the file or expression.||
||-baseuri base-uri||Use the specifed base uri instead of the base URI from the file or expression||
||-r,-recurse||Recursively put directories. If any argument is a directory then it is recursed||
||-m,-maxfiles num||Send files in batch at must num files in one transaction||
||-t,-text||Stores the document as "text" content type||
||-b,-binary||Stores the document as "binary" content type||
||-x,-xml||Stores the document as "xml" content type||
||-d,-mkdirs||Create directories as needed. Only creates direct parent directories of documents||
||-maxthreads n||Use at most n threads, default=1||
||-collection name [-collection name2 ...]||Put document(s) in the named collection(s)||
||-forest id [-forest id2 ...]||Put document(s) in the forest(s) specified by ID||
||-perm,-permission perm [-perm perm ...]||Apply the permission(s) to the document(s)||
||-repair none|full|default||Specify the repair mode||
||-buffer size||Set the transfer buffer size||
||-language lang||Set the language||
||-md5||Store an xmd5 property with the document||
||-namespace namespace||Set the document namespace||
||-resolve,+resolve||Resolve (do not Resolve) Entities before storing the document||
||-quality quality||Set the document quality||
||-locale locale||Set the locale||
||-f,-filenames file||Use a file (or stdin in "-") to specify the list of files to put||
||-delete||Deletes file after successfully putting to marklogic.||
||-stream port||Reads documents from the named port.||
||expression | file||The file (or expression , variable, port or url) to put to the Mark Logic server.||


If file is omitted then stdin is used.
If neither -x, -t or -b is specified then the content type is determined by the server.

====URIs====
If the uri contains {random} it will be replaced by a random number.
If the uri contains {seq} it will be replaced by the by an incrementing sequence number.
This allows you to completely ignore the local filename and put batches of files with unique names.
For example
ml:put -uri "/contacts/contact{seq}.xml" *.xml

will generate uris like
/contacts/contact1.xml
/contacts/contact2.xml

This is particularly useful if the input came from a tool like [[CommandXsplit xsplit]]
where the filenames are not particulary useful but you dont want to do anything fancy like [[CommandXmove xmove]]



====Examples====
Assuming the prefix "ml" is imported as the marklogic module.

Put the file "test.xml" using its full path as the uri
%%
ml:put test.xml
%%

Puts the file "test.xml" using the uri "myfile.xml"
%%
ml:put -uri myfile.xml test.xml
%%

Puts the dynamic document <foo/> to the ML server using the uri "test.xml"

%%
ml:put -uri test.xml <[ <foo/> ]>
%%

Puts the result of an xquery (via stdin) to the Mark Logic server using the uri "test.xml"
%%
xquery -q 'myquery.xquery' -i input.xml | ml:put -uri test.xml
%%

Copies an entire directory tree "modules" to the /modules/ directory on the ML server, using at most 100 files per batch
%%
ml:put -baseuri / -r -m 100 modules
%%

Inserts a document into 2 collections
%%
ml:put -uri test.xml -collection foo -collection bar test.xml
%%

====Permissions====
Permissions can be specified with the -permission (or -perm) option. Permissions take the form of
*capability:role*

Capibility may be one of
- u|update Update
- r|read Read
- i|insert Insert
- x|execute Execute

Role is the role name

Example, add a document with read and update capability to the "user" role
%%
ml:put -uri test.xml -perm read:user -perm u:user test.xml
%%

If the **-md5** option is set then a property is stored with the document of the form
<xmd5 md5="md5checksum" length="length" />

This can be used to implement an efficient "sync" command which only updates the destination if it has changed.


=====Notes=====
Like most xmlsh commands, anywhere an input file is expected, a file, uri, expression, port, or variable expression may be used instead.

For detailed explanation of all the options, see the [[http://developer.marklogic.com/pubs/4.1/books/xcc.pdf MarkLogic XCC Developers Guide]] and the [[http://developer.marklogic.com/pubs/4.1/javadoc/com/marklogic/xcc/package-summary.html XCC Package Summary]].

The put command uses the XCC [[http://developer.marklogic.com/pubs/4.1/javadoc/com/marklogic/xcc/Session.html#insertContent Session.insertContent]] API.


===Streaming===

Careful use of the -filenames option can allow streaming multithreaded puts. The filenames are read and put (possibly batched by the -m and -maxthreads options) as they are read. If this comes from a pipe (like stdin) the list of files can be generated dynamically by a streaming process such as xsplit. This allows large xml files or sets of files to be streamed to a MarkLogic server as they are generated.

Note that if -mkdirs is specifed with -filenames then the list of files must be read in its entirety so that directories can be precreated before any files are put. This negates the ability to stream the puts as the filenames are read.

===Port Streaming===

If -stream port option is given then documements are read directly from the named pipe ( see [[CommandM=Xmkpipe xmkpipe]] ). Since the documents have no name, a base URI and uri template need to be supplied.
A URI template is a string containing {seq} or {random} which evaluates to a sequential or random number.
For example -uri test{seq}.xml will produce incremental unique URI's.

Example using xsplit to split a large XML file into smaller documents and put to marklogic without use of temporary files

%%
import module ml=marklogic
xmkpipe -xml pipe

ml:put -baseuri /test/ -uri "doc{seq}.xml" -maxthreads 4 -maxfiles 100 -stream pipe &

xsplit -stream pipe file.xml
xmkpipe -close pipe
wait

%%



----
[[ModuleMarkLogic MarkLogic Extension Module]]