Searching Entanglement#

In this section, we will go over several ways to search the Entanglement graph. We will cover the following topics:

Searching on the Web Application #

The easiest way to search the Entanglement graph is to use the web application. You can access the web application at app.geodesic.seerai.space. Log in if prompted and click the top hex button to open up the Entanglement page. At the top of the page, you will find the search bar and project selector.

To search, simply select the project you would like to search in with the drop down, then type in the search bar and press enter. The results will be displayed in the graph below. You can click on a node to bring up the radial menu to see more information about it. When entering a search query, the terms will be matched against all text found in the node’s name, alias, description, keywords, and item fields. The search is case insensitive and will return all nodes that contain any of the search terms.

Advanced Search Features #

While this is useful for quick searches, it may return a lot of extra nodes that you are not interested in. To apply more search filters, you can use advanced search features. This allows you to use binary operators like AND, OR, and NOT to filter the results. You can also specify which field you would like to search in specifically. For example, if you only want to search in the name field, you can use the syntax name:'search term'. The format always follows <field name>:'<search terms>' for term search and for exact matches follows <field name>='<exact match>'. Note the quotes around the search term. Single or double quotes are both acceptable. Field names can also be any one of the qulifiers defined on a node such as domain, category, or type. Here are some more examples:

name:'landsat' - Search for nodes with the name field containing ‘landsat’
name='landsat-8' - Search for nodes with the name field exactly matching ‘landsat-8’
alias:'landsat' AND domain='earth-observation' - Search for nodes with the alias field containing ‘landsat’ and the domain field exactly matching ‘earth-observation’
name:'suncor' AND NOT description:'corporate' - Search for nodes with the name field containing ‘suncor’ and the description field not containing ‘corporate’

GraphQL Queries #

The most advanced search feature is the ability to enter GraphQL queries. For general information about GraphQL and how to write queries, see the GraphQL documentation. To open the GraphQL editor, click the button pictured above. This will open the editor with a sample query as well as predefined fragments that will make writing queries easier. The numbers on the image label the differnt parts of the editor which will be explored in more detail below.

Lets look at the parts of the editor to better understand how to use it:

Query Window - This is where you write your query. The query is a JSON object that follows the GraphQL syntax. The query is made up of fields that you want to return and arguments that you want to filter by.
Variables and Headers - This is where you can define variables that you can use in your query. Variables are defined as JSON objects and can be used in the query by using the syntax $<variable name>. Notice that in the default query, the variable $projects is defined and used in the query. You can modify the list of projects in this window to search in a different or multiple projects.
Response Window - This is where the results of the query will be displayed. The results will be displayed in JSON format and will be the same format as the query. The results will also be displayed in the graph after the query is run.
Docs and History - This is where you can find the documentation for the GraphQL schema and the history of queries that you have run. The docs page is autogenerated from the GraphQL schema and is a good way to understand what fields are allowed in the queries. The history will show the query, the variables used, and the response. You can click on a query to run it again or modify it.

GraphQL is a powerful tool to query the graph and can be used to filter the results in many ways. The easiest way to get started is to just change the variables in the bottom panel. Here the default query shows the variables project and search. The project variable is a list of projects that you want to search in. You can add or remove projects from this list to search in different projects. The search variable is the search term that you want to search for. You can modify this to search and it follows all rules listed above for the search bar.

{"projects": ["global"], "search": ""}

In the query window, we can see the full query that is run. The query is made up of fields that you want to return and arguments that you want to filter by. The query is a JSON object and will return all fields that are requested.

query Graph($projects: [String!]!, $search: String) {
    graph(projects: $projects, search: $search) {
        ...objectParts
        connections(predicate: "links") {
            ...connectionParts
        }
    }
}

To make things easy we have defined two fragments ...objectParts and ...connectionParts. These are defined just below and contain all fields that can be returned by objects and connections.

Note

You should not modify these unless you know what you are doing. It can interfere with the graph state and cause errors in the graph window.

fragment objectParts on Object {
    uid
    class
    domain
    href
    category
    type
    name
    project
    description
    xid
    alias
    canonical
    item
    geometry
}

fragment connectionParts on Connection {
    subject {
        ...objectParts
    }
    predicate
    object {
        ...objectParts
    }
}

If you would like to find connections with a specific predicate, you can change that in the query. The line connection(predicate: "links") in the default query will only expand graph connections along predicates called “links”. You can change this to any predicate that you would like to expand along.

To run the query, simply press the play button in the top right of the editor. The results will be displayed in the response window and in the graph.

Searching in the Python API #

The Geodesic Python API can also be used to search the Entanglement graph. This is perfect for working inside of a Jupyter notebook or when running scripts. To search the graph, use the get_objects() method in the entanglement package:

This will search in the default project, or whatever project is set to active in the API.

import geodesic

geodesic.set_active_project('global')

# Search for nodes with the name field containing 'landsat'
results = geodesic.get_objects(search='landsat')

# Print the results
for result in results:
    print(f'{result.alias}: {result.description}')

You can also specify a list of projects to search in by passing the projects argument:

results = geodesic.get_objects(search='landsat', projects=['global', 'my_project'])

The search field also follows the same rules as the web application search bar. For example:

results = geodesic.get_objects(search='name:"landsat" OR domain:"earth-observation"')

The full GraphQL API is also available in the Python API. To use the GraphQL API, use the entanglement.graphql package:

from geodesic.entanglement import graphql

# Run a query to find all nodes with the name field containing 'landsat'
query = """
    {
    graph(projects: ["global"], search: "landsat") {
        ...objectParts
        connections(predicate: "links") {
            ...connectionParts
        }
    }
    }
"""

# Run the query
results = graphql.graph(query)

# Print the results
for result in results['graph']:
    print(f'{result["name"]}: {result["description"]}')

Notice that the same fragments in the Web Application are used in the Python API.

Searching Entanglement#

Searching on the Web Application#

Advanced Search Features#

GraphQL Queries#

Searching in the Python API#

Searching on the Web Application #

Advanced Search Features #

GraphQL Queries #

Searching in the Python API #