Search
Datasets can be searched for within their containing workspace. Searches can filter datasets by arbitrary text, channel name, or tag name.
See here for more information on constructing a search filter query.
Requests
- Search for datasets in a workspace by free text
- Search for datasets in a workspace by channel name
- Search for datasets in a workspace by tag name
- Search for datasets in a workspace using msearch
Search for datasets in a workspace by free text
GET
/api/workspaces/{workspaces-id}/search?q={free-text}
Searches the workspace {workspace-id} for datasets by the free text {free-text}.
Prerequisites
- Workspace
{workspace-id}must exist
Request
Example Snippets
cURL
curl -H "Authorization: Bearer $ACCESS_TOKEN" 'https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=data%20warehouse' -i -X GET \
-H 'Accept: application/json, application/javascript, text/javascript, text/json'
Python (requests)
import requests
url = "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=data%20warehouse"
headers = {
'Authorization': ACCESS_TOKEN
}
response = requests.request("GET", url, headers=headers)
print(response.text.encode('utf8'))
Response
200 OK
{
"_embedded" : {
"datasets" : [ {
"id" : "b25dddc0-32ad-420e-b602-ffccbbbcb553",
"published" : "2025-08-17T18:39:05.28824",
"alias" : "analytics-tables",
"workspaceId" : "9a083a08-cbd7-4889-af7f-03d093b29d1c",
"source" : "no-picture",
"title" : "What tables are in our #fantastic data warehouse?",
"description" : "# Overview\nThis example is a standalone data set with no visualisation.\n\n## What tables are in my data warehouse\nOur query in this dataset selects all the tables in the same schema we have configured the workspace to use.\n```SHOW TABLES```\n\n## Notes\nThe query is database specific. The #postgres query is\n\n```SELECT * FROM pg_tables where schemaname = 'itofyzf'```",
"visualisation" : "{\"google-chart\": {\"chartType\": \"Table\", \"options\": {\"title\": \"Tables\"}}}",
"metadata" : " { \"name\":\"table_model\", \"label\":\"Analytics Tables\", \"related_table\":{ \"columns\":[ { \"name\":\"schemaname\", \"label\":\"Schema Name\" } ] } }",
"query" : "SELECT schemaname \"table_model.schemaname\",tablename \"table_model.tablename\",tableowner \"table_model.tableowner\"FROM pg_tables where schemaname = 'itofyzf'",
"likeCount" : 0,
"likedByProfiles" : [ ],
"commentCount" : 0,
"viewCount" : 0,
"created" : "2025-08-17T18:39:05.288239",
"score" : 20.599281,
"_links" : {
"self" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553"
},
"delete dataset" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553",
"type" : "DELETE"
},
"edit dataset" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553",
"type" : "PATCH"
},
"data" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/data",
"type" : "GET"
},
"source" : {
"href" : "https://app.matatika.com/api/channels/ecb77248-2206-4103-83ce-36a338bd06b9",
"type" : "GET"
},
"new comment" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/comments",
"type" : "POST"
},
"add like" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/like",
"type" : "PUT"
},
"add view" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/view",
"type" : "PUT"
},
"new alert" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/alerts"
},
"add subscription" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/subscriptions"
},
"new message" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/messages"
}
},
"_embedded" : {
"source" : {
"name" : "no-picture",
"description" : "No picture",
"picture" : "https://s.gravatar.com/avatar/8f4ad8fa0793181b761d030196e62053?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fsu.png"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=data%20warehouse&page=0&size=20"
}
},
"page" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 0
}
}
204 No Content
No response body provided.
Search for datasets in a workspace by channel name
GET
/api/workspaces/{workspaces-id}/search?q=in:{channel-name}
Searches the workspace {workspace-id} for datasets by the channel {channel-name}.
Prerequisites
- Workspace
{workspace-id}must exist
Request
Example Snippets
cURL
curl -H "Authorization: Bearer $ACCESS_TOKEN" 'https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=in%3Amatatika-limited%20' -i -X GET \
-H 'Accept: application/json, application/javascript, text/javascript, text/json'
Python (requests)
import requests
url = "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=in%3Amatatika-limited%20"
headers = {
'Authorization': ACCESS_TOKEN
}
response = requests.request("GET", url, headers=headers)
print(response.text.encode('utf8'))
Response
200 OK
Dataset collection with HAL links.
{
"_embedded" : {
"datasets" : [ {
"id" : "573d1e4c-c21d-4732-af6f-bbce5ffa5328",
"published" : "2025-08-17T18:39:05.289801",
"alias" : "simple-bar-chart",
"workspaceId" : "9a083a08-cbd7-4889-af7f-03d093b29d1c",
"source" : "matatika-limited",
"title" : "How many people have visited our website?",
"description" : "# Some Markdown\n- point 1\n- point 2\n- point 3\n",
"questions" : "[''This is my question'', ''this is second question'']",
"visualisation" : "{\"google-chart\": {\"chartType\": \"BarChart\",\"options\": {\"title\": \"Website visitors\"}}}",
"query" : "SELECT to_char(date(report_date),'YYYYMM') as year_month, SUM(sessions) \n FROM\n \"google_analytics_website_overview\"\n WHERE\n \"google_analytics_website_overview\".\"report_date\" >= DATE(NOW()) - INTERVAL '365 DAY'\n GROUP BY year_month\n ORDER BY year_month ASC;",
"likeCount" : 0,
"likedByProfiles" : [ ],
"commentCount" : 0,
"viewCount" : 0,
"created" : "2025-08-17T18:39:05.289799",
"score" : 18.768946,
"_links" : {
"self" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328"
},
"delete dataset" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328",
"type" : "DELETE"
},
"edit dataset" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328",
"type" : "PATCH"
},
"data" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/data",
"type" : "GET"
},
"source" : {
"href" : "https://app.matatika.com/api/channels/bdd964dc-be71-48df-8c4d-aec88482dead",
"type" : "GET"
},
"new comment" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/comments",
"type" : "POST"
},
"add like" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/like",
"type" : "PUT"
},
"add view" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/view",
"type" : "PUT"
},
"new alert" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/alerts"
},
"add subscription" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/subscriptions"
},
"new message" : {
"href" : "https://app.matatika.com/api/datasets/573d1e4c-c21d-4732-af6f-bbce5ffa5328/messages"
}
},
"_embedded" : {
"source" : {
"name" : "matatika-limited",
"description" : "Matatika Limited",
"picture" : "https://cdn.auth0.com/avatars/ml.png?ssl=1"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=in%3Amatatika-limited%20&page=0&size=20"
}
},
"page" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 0
}
}
204 No Content
No response body provided.
Search for datasets in a workspace by tag name
GET
/api/workspaces/{workspace-id}/search?q=tag:{tag-name}
Searches the workspace {workspace-id} for datasets by the tag {tag-name}.
Prerequisites
- Workspace
{workspace-id}must exist
Request
Example Snippets
cURL
curl -H "Authorization: Bearer $ACCESS_TOKEN" 'https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=tag%3Apostgres' -i -X GET \
-H 'Accept: application/json, application/javascript, text/javascript, text/json'
Python (requests)
import requests
url = "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=tag%3Apostgres"
headers = {
'Authorization': ACCESS_TOKEN
}
response = requests.request("GET", url, headers=headers)
print(response.text.encode('utf8'))
Response
200 OK
{
"_embedded" : {
"datasets" : [ {
"id" : "b25dddc0-32ad-420e-b602-ffccbbbcb553",
"published" : "2025-08-17T18:39:05.28824",
"alias" : "analytics-tables",
"workspaceId" : "9a083a08-cbd7-4889-af7f-03d093b29d1c",
"source" : "no-picture",
"title" : "What tables are in our #fantastic data warehouse?",
"description" : "# Overview\nThis example is a standalone data set with no visualisation.\n\n## What tables are in my data warehouse\nOur query in this dataset selects all the tables in the same schema we have configured the workspace to use.\n```SHOW TABLES```\n\n## Notes\nThe query is database specific. The #postgres query is\n\n```SELECT * FROM pg_tables where schemaname = 'itofyzf'```",
"visualisation" : "{\"google-chart\": {\"chartType\": \"Table\", \"options\": {\"title\": \"Tables\"}}}",
"metadata" : " { \"name\":\"table_model\", \"label\":\"Analytics Tables\", \"related_table\":{ \"columns\":[ { \"name\":\"schemaname\", \"label\":\"Schema Name\" } ] } }",
"query" : "SELECT schemaname \"table_model.schemaname\",tablename \"table_model.tablename\",tableowner \"table_model.tableowner\"FROM pg_tables where schemaname = 'itofyzf'",
"likeCount" : 0,
"likedByProfiles" : [ ],
"commentCount" : 0,
"viewCount" : 0,
"created" : "2025-08-17T18:39:05.288239",
"score" : 9.552709,
"_links" : {
"self" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553"
},
"delete dataset" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553",
"type" : "DELETE"
},
"edit dataset" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553",
"type" : "PATCH"
},
"data" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/data",
"type" : "GET"
},
"source" : {
"href" : "https://app.matatika.com/api/channels/926f1357-4763-4875-a0c5-71b28367d563",
"type" : "GET"
},
"new comment" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/comments",
"type" : "POST"
},
"add like" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/like",
"type" : "PUT"
},
"add view" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/view",
"type" : "PUT"
},
"new alert" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/alerts"
},
"add subscription" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/subscriptions"
},
"new message" : {
"href" : "https://app.matatika.com/api/datasets/b25dddc0-32ad-420e-b602-ffccbbbcb553/messages"
}
},
"_embedded" : {
"source" : {
"name" : "no-picture",
"description" : "No picture",
"picture" : "https://s.gravatar.com/avatar/8f4ad8fa0793181b761d030196e62053?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fsu.png"
}
}
} ]
},
"_links" : {
"self" : {
"href" : "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/search?q=tag%3Apostgres&page=0&size=20"
}
},
"page" : {
"size" : 20,
"totalElements" : 1,
"totalPages" : 1,
"number" : 0
}
}
204 No Content
No response body provided.
Search for datasets in a workspace using msearch
POST
/api/workspaces/{workspace-id}/datasets/_msearch
Searches the workspace {workspace-id} for datasets using an elastic search query.
Prerequisites
- Workspace
{workspace-id}must exist
Request
Example Snippets
cURL
curl -H "Authorization: Bearer $ACCESS_TOKEN" 'https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/datasets/_msearch' -i -X POST \
-H 'Accept: application/json, application/javascript, text/javascript, text/json' \
-H 'Content-Type: text/plain; charset=ISO-8859-1' \
-d '{"preference":"search"}
{
"query":{
"bool":{
"must":[
{
"bool":{
"must":{
"bool":{
"should":[
{
"multi_match":{
"query":"data warehouse",
"fields":[
"title"
],
"type":"cross_fields",
"operator":"and"
}
},
{
"multi_match":{
"query":"data warehouse",
"fields":[
"title"
],
"type":"phrase",
"operator":"and"
}
},
{
"multi_match":{
"query":"data warehouse",
"fields":[
"title"
],
"type":"phrase_prefix",
"operator":"and"
}
}
],
"minimum_should_match":"1"
}
}
}
}
]
}
},
"highlight":{
"pre_tags":[
"<mark>"
],
"post_tags":[
"</mark>"
],
"fields":{
"title":{
}
},
"require_field_match":false
},
"size":10,
"_source":{
"includes":[
"*"
],
"excludes":[
]
}
}'
Python (requests)
import requests
url = "https://app.matatika.com/api/workspaces/9a083a08-cbd7-4889-af7f-03d093b29d1c/datasets/_msearch"
data = {"preference":"search"}
{
"query":{
"bool":{
"must":[
{
"bool":{
"must":{
"bool":{
"should":[
{
"multi_match":{
"query":"data warehouse",
"fields":[
"title"
],
"type":"cross_fields",
"operator":"and"
}
},
{
"multi_match":{
"query":"data warehouse",
"fields":[
"title"
],
"type":"phrase",
"operator":"and"
}
},
{
"multi_match":{
"query":"data warehouse",
"fields":[
"title"
],
"type":"phrase_prefix",
"operator":"and"
}
}
],
"minimum_should_match":"1"
}
}
}
}
]
}
},
"highlight":{
"pre_tags":[
"<mark>"
],
"post_tags":[
"</mark>"
],
"fields":{
"title":{
}
},
"require_field_match":false
},
"size":10,
"_source":{
"includes":[
"*"
],
"excludes":[
]
}
}
headers = {
'Authorization': ACCESS_TOKEN
}
response = requests.request("POST", url, headers=headers, data=data)
print(response.text.encode('utf8'))
Response
200 OK
{
"took" : 122,
"timed_out" : false,
"_shards" : {
"failed" : 0.0,
"successful" : 2.0,
"total" : 2.0,
"skipped" : 0.0
},
"hits" : {
"total" : {
"relation" : "eq",
"value" : 1
},
"hits" : [ {
"_index" : "datasets",
"_id" : "b25dddc0-32ad-420e-b602-ffccbbbcb553",
"_score" : 42.620228,
"_source" : {
"id" : "b25dddc0-32ad-420e-b602-ffccbbbcb553",
"tags" : [ "fantastic", "postgres" ],
"title" : "What tables are in our #fantastic data warehouse?",
"description" : "# Overview\nThis example is a standalone data set with no visualisation.\n\n## What tables are in my data warehouse\nOur query in this dataset selects all the tables in the same schema we have configured the workspace to use.\n```SHOW TABLES```\n\n## Notes\nThe query is database specific. The #postgres query is\n\n```SELECT * FROM pg_tables where schemaname = 'itofyzf'```",
"workspaceId" : "9a083a08-cbd7-4889-af7f-03d093b29d1c",
"workspaceOwnerProfile" : "auth0|5eb0327cbfd7490bff55feeb",
"inChannelName" : "no-picture",
"channelName" : "no-picture",
"channelDescription" : "No picture",
"channelPicture" : "https://s.gravatar.com/avatar/8f4ad8fa0793181b761d030196e62053?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fsu.png",
"comments" : [ ],
"alias" : "analytics-tables",
"visualisation" : "{\"google-chart\": {\"chartType\": \"Table\", \"options\": {\"title\": \"Tables\"}}}",
"metadata" : " { \"name\":\"table_model\", \"label\":\"Analytics Tables\", \"related_table\":{ \"columns\":[ { \"name\":\"schemaname\", \"label\":\"Schema Name\" } ] } }",
"likedByProfiles" : [ ],
"likeCount" : 0,
"viewCount" : 0,
"commentCount" : 0,
"created" : "2025-08-17T18:39:05.288239Z",
"lastModified" : "2025-08-17T18:39:05.28824Z",
"lastModifiedMillisDay" : 67145288,
"query" : "SELECT schemaname \"table_model.schemaname\",tablename \"table_model.tablename\",tableowner \"table_model.tableowner\"FROM pg_tables where schemaname = 'itofyzf'",
"lastCommentDate" : "2025-08-17T18:39:05.288239Z",
"lastCommentMillisDay" : 67145288
}
} ],
"max_score" : 42.620228
}
}
204 No Content
No response body provided.