Returns a ResourceList of all datasets, datasets that are immediate children of the specified parent_collection_id, or datasets that match the specified query string. The default is the first 20 datasets, but appending .all() returns a representation of all matching datasets.

The examples below demonstrate how to use .all() and list slicing to obtain the datasets you want.

By default you don’t get any snapshot data. If you set row_limit > 0, the API returns the specified number of data records (rows) from each snapshot as well (maximum 10,000 rows). See the examples below.

Required arguments

None

Optional keyword arguments

NameTypeDescriptionRequired?
filter array Returns only datasets where the specified attribute matches the specified value1. Currently display_name, created_at, data_updated_at, and schema_updated_at are the only attributes supported. You cannot combine this parameter with the query parameter. Note that date comparisons are always non-inclusive, so data_updated_at<=2018-04-06 is the same as data_updated_at<2018-04-06. false
has_tag array Returns only datasets tagged with the specified tag names (for example, construction or real%20estate). If you specify multiple tags, the API returns datasets with any of the tags (OR). false
in_collection_id string Works in conjunction with query and returns only rows from datasets within the specified collection (including its child collections). false
include_serialids boolean Set to true to include the Enigma Serial ID field in the row data (default is false). The serial ID is row identifier added by Enigma that is unique within the current snapshot. false
match_metadata boolean Works in conjunction with query. When true, the API searches for datasets where there is a match within the dataset metadata. When false, the API does not search the metadata for matches. Default is true. false
match_rows boolean Works in conjunction with query. When true, the API searches for datasets where there is a match within the data records (rows). When false, the API does not search the data records for matches. Default is true. false
max_row_count integer Returns only datasets with less than the specified number of rows. false
min_row_count integer Returns only datasets with at least the specified number of rows. false
mode string Values: advanced phrase simple
Defaults to simple.
false
parent_collection_id array Returns only datasets whose immediate parent collection ID matches the one specified here. You can use this to identify all the datasets, plus the current snapshot ID for each, within a given collection. false
phrase_distance integer If mode is set to phrase, this specifies the proximity search distance. For example, if query is sovereign%20country and phrase_distance=0, the two words must be next to each other. If phrase_distance=1, it also matches 'sovereign island country'. false
query string Query string to return only rows that contain specific information (must set row_limit > 0)3. You cannot combine this with the filter parameter. false
row_limit integer Number of rows to return for each dataset (default is 0; maximum 10,000). false
row_offset integer Number of rows to skip at the beginning of the snapshot (for example, row_offset=10 skips the first 10 rows). false
row_sort string Specifies the field used to sort the records within the dataset (must set row_limit > 0). If you specify row_offset as well, the records are sorted first and then the offset is applied. Prepend the field name with a minus sign (-) to specify descending order (defaults to ascending). false
sort array List of dataset attributes indicating how to sort the datasets2. display_name, created_at, data_updated_at, and schema_updated_at are supported. For example, -created_at sorts the datasets by creation date, with the most recent listed first. display_name is the default sort attribute. You cannot combine this with the query parameter. false

1 See Using the filter parameter below.

2 See Using the sort parameter below.

3 See Using the query parameter below.

Using the filter parameter

The examples below show how to use the filter parameter. Note that display_name, created_at, and data_updated_at are the only attributes currently supported:

  • filter='display_name=PhilGEPS - Awards' returns only datasets named “PhilGEPS - Awards.” It works for exact matches only.
  • filter='display_name<G' returns only datasets with names with first letter less than ‘G’.
  • filter='data_updated_at>2017-11-29' returns datasets with snapshots updated since the specified date.

Using the sort parameter

The sort parameter determines the order in which datasets are returned by the API. The default is by display_name in ascending order, but you can also sort by created_at, data_updated_at, and schema_updated_at. To sort in descending order, include a minus sign, for example, sort=-created_at.

For datasets that haven’t been updated, data_updated_at and schema_updated_at will be null. Null values are returned as “the most recent,” so if you want to sort by -data_updated_at or -schema_updated_at to obtain the most recently updated datasets, you’ll need to filter out those with null values. You can do this using the filter parameter with the value >1970, for example sort='-data_updated_at', filter='data_updated_at>1970'.

Using the query parameter

The query parameter lets you specify a search string. If you do, the API returns only rows containing the words you specify. Note that you must set row_limit to a value greater than 0 to get data records in the response.

If you specify multiple words, the default operator is AND, meaning the API returns rows containing all of the words specified. You can include the same advanced search operators supported by the Enigma Public UI to perform other operations, for example, query='enigma||technoligies~1', row_limit=10.

Returns

A ResourceList of dataset models.

If you append a list slicing operator ([]), the SDK returns a Python generator. You can iterate over a ResourceList as you would a list.

Examples

Example 1 returns the first 20 datasets (by display name).

public = enigma.Public()
datasets = public.datasets.list()

Example 2 returns the first, third, fifth, seventh, and nineth datasets (by display name) within the specified collection.

public = enigma.Public()
parent_id = 'b4c9a21a-79d1-495e-a6ea-d643a3820b43'
datasets = public.datasets.list(parent_collection_id=[parent_id])[0:10:2]

Example 3 returns all datasets that include the phrase “enigma technologies” in the metadata or the table rows.

public = enigma.Public()
datasets = public.datasets.list(query="enigma technologies").all()

Example 4 prints the first matching row of the first dataset that contains the words federal and reserve.

public = enigma.Public()
datasets = public.datasets.list(
    query='federal reserve', 
    match_metadata=False, 
    row_limit=1
    )[0:1]
for dataset in datasets:
    print(dataset.current_snapshot.table_rows.rows)
[['TABLE II Deposits and Withdrawals of Operating Cash', '2017-04-28T00:00:00', '17-04', '2017', '4', '28', 'Friday', None, 'Withdrawal', None, None, '0', '0', 'Transfers to Federal Reserve Account ( Table V )', 'Transfers to Federal Reserve Account ( Table V )', '0', '0', '0', '2018-02-12T00:00:00', None, 'https://www.fms.treas.gov/fmsweb/viewDTSFiles?dir=a&fname=17042800.txt']]