Skip to content

How to use the Search API / SearchServiceClient

Introduction

In the FAIR context, the discoverability of data plays one of the most important roles, as even the best data will simply lie unused without a way to be found. Aruna provides a public search index in which specific metadata of all public objects can be searched. The user-defined scope of the search can be adjusted from fuzzy to detailed. A normal search query includes all fields but can be additionally filtered.

Depending on the type of field, different operators are useful for filtering:

Field Type Examples
name String name != genome.fasta
description String description != ''
object_type Enum object_type = PROJECT, object_type IN [COLLECTION, DATASET]
object_type_id Int object_type_id = 1, object_type_id IN [2,3], object_type_id > 1
count Int count > 1, count 1234 TO 123456
size Int size > 123456, size 1234 TO 123456
status Enum status = AVAILABLE, status NOT DELETED
labels Struct labels.variant = LABEL AND labels.key = validated AND labels.value = true,
labels.variant = HOOK AND labels.key = my_validator
data_class Enum data_class = PUBLIC
created_at Int created_at > 1698238293, created_at 1696111200 TO 1698793200
metadata_license String metadata_license = CC0, metadata_license IN [CC0, CC-BY-SA-4.0, MIT]
data_license String data_license = CC0, data_license IN [CC0, CC-BY-SA-4.0, MIT]

These filters can be combined with the AND and OR expressions and nested with brackets (...) for complex queries.
An in-depth documentation to the filter operator usage can be found in the Meilisearch Filter expressions documentation.

If a user finds an interesting resource but does not have enough access permissions, an access request with a personal message can be sent to the creator of the resource which will be delivered via a personal notification. This can be used to contact the user who created the Object on the first hand.

Search resources

API examples of how to search resources.

The limit and offset parameter can be used to paginate the requests.

  • limit defines how many hits are returned and must be between 1 and 100 (inclusive).
  • offset parameter defines how many hits are ignored before the next batch of hits are returned.
Required permissions

This request does not require any permissions or authentication.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Native JSON request to fuzzy search for a keyword
curl '
  {
    "query": "fasta",
    "filter": "",
    "limit": "100",
    "offset": "0"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/search

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Native JSON request to specifically search for a keyword
curl '
  {
    "query": "\"genome.fasta\"",
    "filter": "",
    "limit": "100",
    "offset": "0"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/search

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Native JSON request to fuzzy search for a keyword with additional filters
curl '
  {
    "query": "fasta",
    "filter": "type = OBJECT",
    "limit": "100",
    "offset": "0"
  }' \
     -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X POST https://<URL-to-Aruna-instance-API-endpoint>/v2/search

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// Create tonic/ArunaAPI request to fuzzy search for a keyword
let request = SearchResourcesRequest {
    query: "fasta".to_string(),
    filter: "".to_string(),
    limit: 100,
    offset: 0,
};

// Send the request to the Aruna instance gRPC endpoint
let response = search_client.search_resources(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// Create tonic/ArunaAPI request to specifically search for a keyword
let request = SearchResourcesRequest {
    query: "\"genome.fasta\"".to_string(),
    filter: "".to_string(),
    limit: 100,
    offset: 0,
};

// Send the request to the Aruna instance gRPC endpoint
let response = search_client.search_resources(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
// Create tonic/ArunaAPI request to fuzzy search for a keyword with additional filters
let request = SearchResourcesRequest {
    query: "fasta".to_string(),
    filter: "type = OBJECT".to_string(),
    limit: 100,
    offset: 0,
};

// Send the request to the Aruna instance gRPC endpoint
let response = search_client.search_resources(request)
                             .await
                             .unwrap()
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Create tonic/ArunaAPI request to fuzzy search for a keyword
request = SearchResourcesRequest(
    query="fasta",
    filter="",
    limit=100,
    offset=0
)

# Send the request to the Aruna instance gRPC endpoint
response = client.search_client.SearchResources(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Create tonic/ArunaAPI request to specifically search for a keyword
request = SearchResourcesRequest(
    query="\"genome.fasta\"",
    filter="",
    limit=100,
    offset=0
)

# Send the request to the Aruna instance gRPC endpoint
response = client.search_client.SearchResources(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
# Create tonic/ArunaAPI request to fuzzy search for a keyword with additional filters
request = SearchResourcesRequest(
    query="fasta",
    filter="type = OBJECT",
    limit=100,
    offset=0
)

# Send the request to the Aruna instance gRPC endpoint
response = client.search_client.SearchResources(request=request)

# Do something with the response
print(f'{response}')

Get public resource(s)

API examples of how to fetch Object information of public resources.

Required permissions

This request does not require any permissions or authentication but the Object information will be returned redacted.

If an authentication token is provided this request requires at least READ permissions on the specific resources.

1
2
3
4
# Native JSON request to fetch information of a public Object
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET https://<URL-to-Aruna-instance-API-endpoint>/v2/resource/{resource-id}

1
2
3
4
# Native JSON request to fetch information of multiple public Objects
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET 'https://<URL-to-Aruna-instance-API-endpoint>/v2/resources?resourceIds=resource-id-01&resourceIds=resource-id-02'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Create tonic/ArunaAPI request to fetch information of a public Object
let request = GetResourceRequest {
    resource_id: "<resource-id>".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = search_client.get_resource(request)
                             .await
                             .unwrap() 
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// Create tonic/ArunaAPI request to fetch information of multiple public Objects
let request = GetResourcesRequest {
    resource_ids: vec![
      "<resource-id-01>".to_string(),
      "<resource-id-02>".to_string(),
      "<...>".to_string(),
    ],
};

// Send the request to the Aruna instance gRPC endpoint
let response = search_client.get_resources(request)
                             .await
                             .unwrap() 
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Create tonic/ArunaAPI request to fetch information of a public Object
request = GetResourceRequest(
    resource_id="<resource-id>"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.search_client.GetResource(request=request)

# Do something with the response
print(f'{response}')

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Create tonic/ArunaAPI request to fetch information of multiple public Objects
request = GetResourceRequest(
    resource_ids=[
      "<resource-id-01>",
      "<resource-id-02>",
      "<...>"
    ]
)

# Send the request to the Aruna instance gRPC endpoint
response = client.search_client.GetResource(request=request)

# Do something with the response
print(f'{response}')

Request access

API examples of how to request access for resources owned by other users.

Required permissions

To request access to a resource you only have to be a registered Aruna user.

1
2
3
4
# Native JSON request to request access to an Object of another user
curl -H 'Authorization: Bearer <AUTH_TOKEN>' \
     -H 'Content-Type: application/json' \
     -X GET 'https://<URL-to-Aruna-instance-API-endpoint>/v2/resource/resource-id/access?message=Would%20you%20please%20give%20me%20access%20to%20this%20dataset%3F'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
// Create tonic/ArunaAPI request to request access to an Object of another user
let request = RequestResourceAccessRequest {
    resource_id: "<resource-id>".to_string(),
    message: "Would you please give me access to this dataset?".to_string(),
};

// Send the request to the Aruna instance gRPC endpoint
let response = search_client.request_resource_access(request)
                             .await
                             .unwrap() 
                             .into_inner();

// Do something with the response
println!("{:#?}", response);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Create Create tonic/ArunaAPI request to request access to an Object of another user
request = RequestResourceAccessRequest(
    resource_id="<resource-id>",
    message="Would you please give me access to this dataset?"
)

# Send the request to the Aruna instance gRPC endpoint
response = client.search_client.RequestResourceAccess(request=request)

# Do something with the response
print(f'{response}')