Entity Keys¶

/api/repositories/{repository}/entities/{entity}/keys

Parameter	Type	Purpose
repository	string	the name of the Repository
entity	int	The ID of the entity to view

Show All¶

GET /api/repositories/(string: repository)/entities/(int: entityID)/keys¶: Lists discovered and permanent keys of the corresponding Entity

GET /api/repositories/jupiter/entities/1/keys HTTP/1.1
Accept: application/json

Response Code	Reason
200	No error
500	Server error

The response will be a Standard Response, with a list of discovered and permanent keys in the corresponding Entity.

The columns array will contain the list of columns for each data row.

Human Name	Column Name	Description
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 Entity:

{
    "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 Entity, rows will be an empty string.

Show Some¶

POST /api/repositories/(string: repository)/entities/(int: entityID)/keys¶

Lists discovered and permanent keys of the corresponding Entity that match various criteria

JSON Parameters:
	body – The request body

POST /api/repositories/jupiter/entities/1/keys HTTP/1.1
Content-Type: application/json

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

Response Code	Reason
200	Success
400	Invalid request body
400	Invalid command
500	Server error

The request requires a Standard Request packet. Available commands are:

Command	Description
get	Lists discovered and permanent keys of an Entity that matches the criteria in Options

The response will be a Standard Response, same as described for the above get requests, with a list of discovered and permanent keys in the corresponding Entity matching the given criteria in Options.

Commands¶

Create¶

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"
    }
}

Response Code	Reason
200	No error
400	Invalid data passed with request
500	Server error

The request requires a Standard Request packet. Available commands are:

Command	Description
create	Create key
discover	Discover key
edit	Edit key status

The request packet must contain the command and data elements.

Name	Mandatory	Description
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:

Value	Description
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:

Value	Example
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 scheduled job.

"uri": "/api/repositories/alpha/scheduler/277"

Discover¶

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"
    }
}

Response Code	Reason
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:

Name	Mandatory	Default Value	Description
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:

Value	Description
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:

Value	Example
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:

Option	Description
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 scheduled job.

"uri": "/api/repositories/alpha/scheduler/276"

Edit¶

POST /api/repositories/alpha/entities/1/keys HTTP/1.1
Content-Type: application/json

{
    "command": "edit",
    "data": {
        "status": "Permanent"
        "attributes": ["1", "2 3"]
    }
}

Response Code	Reason
204	Success
400	Invalid data passed with request
500	Server error

The request packet must contain the command and 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.

Delete¶

DELETE /api/repositories/(string: repository)/entities/(int: entityID)/keys¶: Delete multiple discovered or permanent keys.

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 attribute IDs of the attrubutes that form the simple/composite keys.

Response Code	Reason
204	Success
400	Invalid data passed with request
500	Server error

Export¶

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

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"
    }
}

Response Code	Reason
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:

Field	Required
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.

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

TSS REST API