Attribute Strings
==================

.. code-block:: http

    /api/repositories/{repository}/entities/{entity}/attributes/{attribute}/values/strings

.. csv-table::
    :header: Parameter, Type, Purpose
    :widths: 20, 20, 60
    :stub-columns: 1

    repository, string, The :doc:`repository <repository>` name
    entity, int, The :doc:`entity <entity>` ID
    attribute, int, The :doc:`attribute <attributes>` ID

.. http:get:: /api/repositories/(string:repository)/entities/(int:entityID)/attributes/(int:attributeID)/values/strings
    :synopsis: Get all data rows with a string value for an attribute

    Gets a complete list of data rows with a string value for an attribute.

.. code-block:: http

    GET /api/repositories/jupiter/entities/1/attributes/3/values/strings HTTP/1.1
    Accept: application/json

The list of rows may be quite long; if so, the list can be paged:

.. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)/attributes/(int:attributeID)/values/strings
    :synopsis: Get a partial list of data rows with a string value for an attribute

    Get a page of rows with a string value for an attribute

.. code-block:: http

    POST /api/repositories/jupiter/entities/1/attributes/3/values/strings HTTP/1.1
    Content-Type: application/json

    {
        "command": "get",
        "options": {
            "pageStart": 1,
            "pageSize": 32
        }
    }

The response is a :doc:`standard-response`.

The ``columns`` array will show the following columns:

.. csv-table::
    :header: Human Name, Column Name, Description
    :widths: 25, 25, 50

    "Value", "VALUE", "The data value"
    "Frequency", "FREQUENCY_COUNT", "The number of times the data value occurs in the attribute"
    "Dist %","_distribution","A measure of how much of the attribute contains the data value"
    "Length","_length","The length of the data value"
    "Soundex","_soundex","The coarse-grain phonetic representation of the data value"
    "Metaphone","_metaphone","The fine-grain phonetic representation of the data value"
    "Pattern","_pattern","The structure of the data value"
    "Mask","_mask","The mask pattern of the data value"
    "Percent Rank","_percentile","The percentile of the data value"
    "Deviation","_deviation","The deviation of the data value"
    "Row Id","_rowid","The row id of the data value"

A ``datarow`` element will look like:

.. code-block:: json

    {
        "dataRow": [
            "ON",
            "46",
            "5.852",
            "2",
            "O500",
            "ON",
            "a2",
            "AA",
            "",
            "",
            "2268"
        ]
    }

Export
-------

Some or all of the rows may be exported as a scheduled task.

.. code-block:: http

    POST /api/repositories/jupiter/entities/1/attributes/3/values/strings HTTP/1.1
    Content-Type: application/json

    {
        "command": "export",
        "data": {
            "filename": "filename.csv",
            "filetype": "csv",
            "encoding": "utf-8"
        },
        "options": {
            "where": "Frequency > 2"
        }
    }

.. csv-table::
    :header: Response Code, Reason
    :widths: 25, 75

    200, No error
    400, Invalid data passed with request
    500, Server error

The request packet must contain the ``command`` and ``data`` elements. The ``options`` element is not required, but may specify the columns to export, and/or the rows to filter.

The following table shows which fields are required in the ``data`` element:

.. csv-table::
    :header: Field, Required
    :widths: 20, 10
    
    filename, Y
    filetype, N
    encoding, N

If ``filetype`` is not specified, it defaults to csv. If ``encoding`` is not specified, it defaults to the server native encoding.

The response will contain the URL of the scheduled task and the link to download the exported file.

.. code-block:: json

    {
        "job": "/api/repositories/jupiter/scheduler/1",
        "file": "/api/repositories/jupiter/download/filename.csv"
    }