//////////////////////////////////////////////////////////////////////////////// /// @brief importer manual /// /// @file /// /// DISCLAIMER /// /// Copyright 2012 triagens GmbH, Cologne, Germany /// /// Licensed under the Apache License, Version 2.0 (the "License"); /// you may not use this file except in compliance with the License. /// You may obtain a copy of the License at /// /// http://www.apache.org/licenses/LICENSE-2.0 /// /// Unless required by applicable law or agreed to in writing, software /// distributed under the License is distributed on an "AS IS" BASIS, /// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. /// See the License for the specific language governing permissions and /// limitations under the License. /// /// Copyright holder is triAGENS GmbH, Cologne, Germany /// /// @author Dr. Frank Celler /// @author Copyright 2012, triAGENS GmbH, Cologne, Germany //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// /// @page ImpManual ArangoDB's Importer Manual (@VERSION) /// /// @NAVIGATE{DbaManual,Home,Glossary} /// /// @if LATEX /// /// @else /// @copydetails ImpManualBasicsTOC /// @endif //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// /// @page ImpManualBasicsTOC /// /// //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// /// @page ImpManualBasics ArangoDB Importer /// /// This manual describes the ArangoDB importer @LIT{arangoimp}, which can be /// used for bulk imports. /// /// @EMBEDTOC{ImpManualBasicsTOC} /// /// The most convenient method to import a lot of data into ArangoDB is to use /// the @LIT{arangoimp} command-line tool. It allows you to import data records /// from a file into an existing database collection. /// /// Let's assume you want to import user records into an existing collection /// named "users" on the server. /// /// @section ImpManualBasicsJson Importing JSON-encoded Data /// /// Let's further assume the import at hand is encoded in JSON. We'll be using /// these example user records to import: /// /// @verbinclude arangoimp-data-json /// /// To import these records, all you need to do is to put them into a file (with /// one line for each record to import) and run the following command: /// /// @LIT{./arangoimp \-\-file "data.json" \-\-type json \-\-collection "users"} /// /// This will transfer the data to the server, import the records, and print a /// status summary. /// /// By default, the endpoint @LIT{tcp://127.0.0.1:8529} will be used. /// If you want to specify a different endpoint, you can use the \-\-server.endpoint /// option. You probably want to specify a database user and password as well. /// You can do so by using the options \-\-server.username and \-\-server.password. /// If you do not specify a password, you will be prompted for one. /// /// @LIT{./arangoimp \-\-server.endpoint tcp://127.0.0.1:8529 \-\-server.username root \-\-file "data.json" \-\-type json \-\-collection "users"} /// /// Note that the collection (@LIT{users} in this case) must already exist or /// the import will fail. If you want to create a new collection with the import /// data, you need to specify the \-\-create-collection option. /// /// @LIT{./arangoimp \-\-file "data.json" \-\-type json \-\-collection "users" \-\-create-collection true} /// /// As the import file already contains the data in JSON format, attribute names /// and data types are fully preserved. As can be seen in the example data, /// there is no need for all data records to have the same attribute names or /// types. Records can be inhomogenous. /// /// @section ImpManualBasicsCsv Importing CSV Data /// /// @LIT{arangoimp} also offers the possibility to import data from CSV /// files. This comes handy when the data at hand is in CSV format already and /// you don't want to spend time converting them to JSON for the import. /// /// To import data from a CSV file, make sure your file contains the attribute /// names in the first row. All the following lines in the file will be /// interpreted as data records and will be imported. /// /// The CSV import requires the data to have a homogenuous structure. All records /// must have exactly the same amount of columns as there are headers. /// /// The cell values can have different data types though. If a cell does not /// have any value, it can be left empty in the file. These values will not be /// imported so the attributes will not "be there" in document created. Values /// enclosed in quotes will be imported as strings, so to import numeric values, /// boolean values or the null value, don't enclose the value into the quotes in /// your file. /// /// We'll be using the following import for the CSV import: /// /// @verbinclude arangoimp-data-csv /// /// The command line to execute the import then is: /// /// @LIT{arangoimp \-\-file "data.csv" \-\-type csv \-\-collection "users"} /// /// Note that the quote and separator characters can be adjusted via the /// @CA{\-\-quote} and @CA{\-\-separator} arguments when invoking arangoimp. /// It is also possible to change the end-of-line character from the default /// value of @LIT{\\n} to another value using the @CA{\-\-eol} argument. /// /// @section ImpManualBasicsCsv Importing TSV Data /// /// You may also import tab-separated values (TSV) from a file. This format /// is very simple: every line in the file represents a data record. There is /// no quoting or escaping. That also means that the separator character /// (which defaults to the tabstop symbol) must not be used anywhere in the /// actual data. /// As with CSV, the first line in the TSV file must contain the attribute /// names, and all lines must have an identical number of values. /// /// If a different separator character or string should be used, it can be /// specified with the @CA{\-\-separator} argument. The end-of-line character /// can be adjusted using the @CA{\-\-eol} argument. /// /// An example command line to execute the TSV import is: /// /// @LIT{arangoimp \-\-file "data.tsv" \-\-type tsv \-\-collection "users" \-\-eol "\\r\\n"} /// //////////////////////////////////////////////////////////////////////////////// // Local Variables: // mode: c++ // mode: outline-minor // outline-regexp: "^\\(/// @brief\\|/// {@inheritDoc}\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @\\}\\)" // End: