Entity Keys =========== .. code-block:: http /api/repositories/{repository}/entities/{entity}/keys .. csv-table:: :header: Parameter, Type, Purpose :widths: 20, 20, 60 :stub-columns: 1 repository, string, the name of the :doc:`repository` entity, int, The ID of the entity to view Show All ~~~~~~~~~ .. http:get:: /api/repositories/(string:repository)/entities/(int:entityID)/keys :synopsis: Lists discovered and permanent keys of an entity Lists discovered and permanent keys of the corresponding :doc:`entity` .. code-block:: http GET /api/repositories/jupiter/entities/1/keys HTTP/1.1 Accept: application/json .. csv-table:: :header: Response Code, Reason :widths: 25, 75 200, No error 500, Server error The response will be a :doc:`standard-response`, with a list of discovered and permanent keys in the corresponding :doc:`entity`. The ``columns`` array will contain the list of columns for each data row. .. csv-table:: :header: Human Name, Column Name, Description :widths: 25, 25, 50 "Lh Attrs", "_lhnames", "The attributes that form the primary key" "Status", "__STATUS", "Whether the key is Discovered or Permanent." "Verified", "_verified", "Whether the key quality has been verified against all rows." "Ref", "JOB_ID", "The key analysis reference number." "Quality %", "GOODNESS", "A measure of how well the attributes form a key" "Keys", "CONFIRMATIONS", "The number of non-duplicated keys." "Duplicate Keys", "_duplicate_keys", "The number of distinct key values that are duplicated." "Duplicate Rows", "_duplicate_rows", "The number of rows with duplicate keys." "Verified Date", "_checked_date", "When the key rule was last verified." "Verified By", "CHECKED_BY", "Who verified the key rule." "Created Date", "_created_date", "When the key rule was created." "Created By", "CREATED_BY", "Who created the key rule." "Rh Attr ID", "RH_ATTR", "Ids of the right hand attributes that form the primary key" "Lh Attr Ids", "LH_ATTRS", "Ids of the left hand attributes that form the primary key" The ``dataRow`` array will contain a list of the permanent and discovered keys of the corresponding :doc:`entity`: .. code-block:: json { "rows": [ { "dataRow": [ "Key", "Discovered", "Yes", "219", "50.000", "1", "2", "5", "2015/03/10 09:44:21", "bob@TEST-7", "", "1 15" ], "metadata": { "url": "/api/repositories/jupiter/entities/22/keys/1_15/duplicates" } } ] } ``metadata`` contains the url to drill down to each row. If there are no discovered or permanent keys in the :doc:`entity`, ``rows`` will be an empty string. Show Some ~~~~~~~~~~ .. http:post:: /api/repositories/(string:repository)/entities/(int:entityID)/keys :synopsis: Lists discovered and permanent keys of an entity that match various criteria Lists discovered and permanent keys of the corresponding :doc:`entity` that match various criteria :jsonparam body: The request body .. code-block:: http POST /api/repositories/jupiter/entities/1/keys HTTP/1.1 Content-Type: application/json { "command": "get", "options": { "pageSize":"2", "pageStart":"1" } } .. csv-table:: :header: Response Code, Reason :widths: 25, 75 200, Success 400, Invalid request body 400, Invalid command 500, Server error The request requires a :doc:`standard-request` packet. Available commands are: .. csv-table:: :header: Command, Description :widths: 20, 80 get, Lists discovered and permanent keys of an :doc:`entity` that matches the criteria in Options The response will be a :doc:`standard-response`, same as described for the above get requests, with a list of discovered and permanent keys in the corresponding :doc:`entity` matching the given criteria in Options. Commands ~~~~~~~~ .. _dek_create: Create ------- .. code-block:: http POST /api/repositories/alpha/entities/1/keys HTTP/1.1 Content-Type: application/json { "command": "create", "data": { "jobName": "Create Key", "attributes": "1", "scheduleNow":"0", "scheduleTime":"2016-11-22 11:40:45" } } .. csv-table:: :header: Response Code, Reason :widths: 25, 75 200, No error 400, Invalid data passed with request 500, Server error The request requires a :doc:`standard-request` packet. Available commands are: .. csv-table:: :header: Command, Description :widths: 30, 70 create, Create :ref:`key ` discover, Discover :ref:`key ` edit, Edit :ref:`key ` status The request packet must contain the :code:`command` and :code:`data` elements. .. csv-table:: :header: Name, Mandatory, Description :widths: 20, 10, 75 jobName, Yes, Name of the create keys job attributes, Yes, It should contain left hand attribute ids that are to be used as a key. scheduleNow, No, Yes (1) / No (0) scheduleTime, No, What time to start. Required: No (if scheduleNow is 1) / Yes (if scheduleNow is 0). If ``scheduleNow`` is 0 and ``scheduleTime`` is not provided, the job will run immediately. ``scheduleNow`` field can be formatted as follows: .. csv-table:: :header: Value, Description :widths: 10, 75 1, Schedule the job immediately 0, Schedule the job at a given date and time (requires ``scheduleTime`` field) ``scheduleTime`` field can be formatted as follows: .. csv-table:: :header: Value, Example :widths: 50, 75 YYYY-Month-DD HH:MM:SS, 2016-JANUARY-01 10:30:45 YYYY/Month/DD HH:MM:SS, 2016/JANUARY/01 10:30:45 YYYY-Mon-DD HH:MM:SS, 2016-JAN-01 10:30:45 YYYY/Mon/DD HH:MM:SS, 2016/JAN/01 10:30:45 YYYY-MM-DD HH:MM:SS, 2016-01-01 10:30:45 YYYY/MM/DD HH:MM:SS, 2016/01/01 10:30:45 The response will contain the URL of the :doc:`scheduled job `. .. code-block:: json "uri": "/api/repositories/alpha/scheduler/277" .. _dek_discover: Discover --------- .. code-block:: http POST /api/repositories/test/entities/1/keys HTTP/1.1 Content-Type: application/json { "command": "discover", "data": { "jobName":"discover keys", "firstRow": "1", "sampleSize": "50", "rowsToSample": { "option": "every", "value": "1" }, "keyUniqueness": "98", "maxAttributes" : "4", "scheduleNow":"0", "scheduleTime":"2016-11-22 11:40:45" } } .. 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 following fields should be sent as part of ``data``: .. csv-table:: :header: Name, Mandatory, Default Value, Description :widths: 10, 10, 12, 75 jobName, No, Keys, Name of the scheduled dicover dependencies job firstRow, No, 1, Start sampling at a given row. The value should be set between 1 and maximum number of rows available. sampleSize, Yes, , How many rows to sample? The value should be set between 1 and maximum number of rows available. rowsToSample, Yes, NA, The options provided here are mutually exclusive. Options are explained further below. keyUniqueness, Yes, , How distinct must your keys be in %? The value should be between 1 & 100. maxAttributes, No, 1, Maximum number of attributes that can form a compound key. The value should be between 1 and maximum number of attributes. scheduleNow, No, NA, Yes (1) / No (0) scheduleTime, No, NA, What time to start. Required: No (if scheduleNow is 1) / Yes (if scheduleNow is 0). If ``scheduleNow`` is 0 and ``scheduleTime`` is not provided, the job will run immediately. ``scheduleNow`` field can be formatted as follows: .. csv-table:: :header: Value, Description :widths: 10, 75 1, Schedule the job immediately 0, Schedule the job at a given date and time (requires ``scheduleTime`` field) ``scheduleTime`` field can be formatted as follows: .. csv-table:: :header: Value, Example :widths: 50, 75 YYYY-Month-DD HH:MM:SS, 2016-JANUARY-01 10:30:45 YYYY/Month/DD HH:MM:SS, 2016/JANUARY/01 10:30:45 YYYY-Mon-DD HH:MM:SS, 2016-JAN-01 10:30:45 YYYY/Mon/DD HH:MM:SS, 2016/JAN/01 10:30:45 YYYY-MM-DD HH:MM:SS, 2016-01-01 10:30:45 YYYY/MM/DD HH:MM:SS, 2016/01/01 10:30:45 The ``rowsToSample`` allow one to select which rows to include in sampling. The options for ``rowsToSample`` are detailed below, they are mutually exclusive, hence you can only selected one of the following options: .. csv-table:: :header: Option, Description :widths: 10, 75 every, Which rows to sample? For every row set value to 1. For every 5 rows set value to 5 and so on. randomPercent, Sample random percentage of rows. The percentage should be set between 1 and 100. prevRandomSelection, Re-use previous random selection. This option must only be set to 1 if you have previously sampled rows using 'randomPercent' option. The response will contain the URL of the :doc:`scheduled job `. .. code-block:: json "uri": "/api/repositories/alpha/scheduler/276" .. _dek_edit: Edit ----- .. code-block:: http POST /api/repositories/alpha/entities/1/keys HTTP/1.1 Content-Type: application/json { "command": "edit", "data": { "status": "Permanent" "attributes": ["1", "2 3"] } } .. csv-table:: :header: Response Code, Reason :widths: 25, 75 204, Success 400, Invalid data passed with request 500, Server error The request packet must contain the :code:`command` and :code:`data` elements. All parameters are mandatory. `status` should be `Permanent` or `Discovered`. `attributes` field should contain an array of left hand attribute ids that are to be used as the key. .. _dek_delete: Delete ------- .. http:delete:: /api/repositories/(string:repository)/entities/(int:entityID)/keys :synopsis: Delete multiple discovered or permanent keys Delete multiple discovered or permanent keys. .. code-block:: http DELETE /api/repositories/jupiter/entities/1/keys HTTP/1.1 Content-Type: application/json { "attributes" : [ "1", "2 4" ] } The ``attributes`` key will have an array of :doc:`attribute ` IDs of the attrubutes that form the simple/composite keys. .. csv-table:: :header: Response Code, Reason :widths: 25, 75 204, Success 400, Invalid data passed with request 500, Server error .. _ek_export: Export ------- Some or all of the rows may be exported as a scheduled task. .. code-block:: http POST /api/repositories/jupiter/entities/1/keys HTTP/1.1 Content-Type: application/json { "command": "export", "data": { "filename": "filename.csv", "filetype": "csv", "encoding": "utf-8" }, "options": { "columns": ["__STATUS", "RH_ATTR", "LH_ATTRS"], "where": "Ref = 1" } } .. 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" }