.. _gt_tools: GeoTools Command-Line Tools =========================== The GeoMesa GeoTools distribution includes a set of command-line tools that can work with most non-GeoMesa data store implementations to provide feature management, ingest and export. This allows the use of GeoMesa converters and output encodings to be used with non-GeoMesa data stores. Installation ------------ GeoMesa GeoTools artifacts are available for download or can be built from source. The easiest way to get started is to download the most recent binary version from `GitHub`__. __ https://github.com/locationtech/geomesa/releases .. note:: The examples below expect a version to be set in the environment: .. parsed-literal:: $ export TAG="|release_version|" $ export VERSION="|scala_binary_version|-${TAG}" # note: |scala_binary_version| is the Scala build version Extract it somewhere convenient: .. code-block:: bash # download and unpackage the most recent distribution: $ wget "https://github.com/locationtech/geomesa/releases/download/geomesa-${TAG}/geomesa-gt_${VERSION}-bin.tar.gz" $ tar xvf geomesa-gt_${VERSION}-bin.tar.gz $ cd geomesa-gt_${VERSION} $ ls bin/ conf/ dist/ docs/ examples/ lib/ LICENSE.txt logs/ Alternatively, it may be built from source. For more information, refer to the instructions on `GitHub `__. If you have built from source, the distribution is created in the ``target`` directory of ``geomesa-gt/geomesa-gt-dist``. Setting up the Command Line Tools ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once installed, the command line tools can be invoked by running the script ``geomesa-gt`` located in the binary distribution under ``geomesa-gt_${VERSION}/bin/``. The tools ship with some default GeoTools data stores, such as support for Postgis and shapefiles. For other stores, you will need to copy the appropriate JARs into the tools ``lib`` folder. .. note:: Environment variables can be specified in ``conf/*-env.sh`` and dependency versions can be specified in ``conf/dependencies.sh``. .. note:: ``geomesa-gt`` will load JARs from the ``$GEOMESA_EXTRA_CLASSPATHS`` environment variable into the class path. Use the ``geomesa-gt classpath`` command in order to see what JARs are being used. Due to licensing restrictions, dependencies for shape file support must be separately installed. Do this with the following command: .. code-block:: bash $ ./bin/install-shapefile-support.sh Run ``geomesa-gt`` without arguments to confirm that the tools work. .. code:: $ bin/geomesa-gt INFO Usage: geomesa-gt [command] [command options] Commands: ... Setting up Distributed Processing ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ GeoMesa supports running map/reduce jobs for ingest and export. If you have a local Hadoop installation, the tools will read the ``$HADOOP_HOME`` environment variable to load the appropriate JAR files for Hadoop. If you do not have a local Hadoop installation, then in order to run distributed jobs you will need to manually install the Hadoop configuration files into the tools ``conf`` folder, and the Hadoop JARs into the tools ``lib`` folder. To install JARs, use the script provided with the distribution: .. code-block:: bash $ ./bin/install-dependencies.sh lib If you installed JARs for any additional data stores, you will need to add them to the Hadoop libjars path by modifying the file ``org/locationtech/geomesa/geotools/tools/gt-libjars.list`` inside the JAR ``lib/geomesa-gt-tools_${VERSION}.jar``. General Arguments ----------------- Most commands require you to specify the connection to your data store. Parameters can be passed in using the ``--param`` argument, which can be repeated in order to specify multiple parameters. Alternatively, the ``--params`` argument can be used to specify a Java properties file containing the parameters. This may be useful for simplifying the command invocation, or to hide sensitive parameters from bash history and process lists. If both ``--param`` and ``--params`` are used, then parameters specified directly will take precedence over ones from the properties file. For example, to connect to a Postgis data store, you may use the following command: .. code:: $ bin/geomesa-gt export --param dbtype=postgis --param host=localhost \ --param user=postgres --param passwd=postgres --param port=5432 \ --param database=example --feature-name gdelt