SearchFilter

The SearchFilter provides text search capabilities across multiple attributes of an entity. It is optimized for text-based searches and is typically used for search fields in list views.

Search modes

The SearchFilter supports two different search modes via the type parameter:

Mode	Description	Requirements
ATTRIBUTE_FILTER	Searches in specified attributes using wildcard matching	attributePaths must be provided
TEXT_SEARCH	Uses database full-text search index	Text index must be configured in Construction Kit, language must be provided

ATTRIBUTE_FILTER mode

The ATTRIBUTE_FILTER mode searches in explicitly specified attributes. The search term is automatically wrapped with wildcards (e.g., test becomes *test*).

query {
  runtime {
    systemCommunicationDataFlow(
      searchFilter: {
        searchTerm: "eda"
        type: ATTRIBUTE_FILTER
        attributePaths: ["name"]
      }
    ) {
      items {
        rtId
        name
        description
      }
    }
  }
}

Multiple attributes

You can search across multiple attributes simultaneously:

query {
  runtime {
    energyCommunityCustomer(
      searchFilter: {
        searchTerm: "berlin"
        type: ATTRIBUTE_FILTER
        attributePaths: ["contact.firstName", "contact.lastName", "contact.address.cityTown"]
      }
    ) {
      items {
        rtId
        contact {
          firstName
          lastName
          address {
            cityTown
          }
        }
      }
    }
  }
}

This query searches for "berlin" in the first name, last name, and city fields.

TEXT_SEARCH mode

The TEXT_SEARCH mode uses a database full-text search index for more efficient and linguistically-aware searching. This mode requires:

1. A text index configured on the entity type in the Construction Kit (indexType=Text)
2. A language parameter specifying the language for text matching

query {
  runtime {
    systemCommunicationDataFlow(
      searchFilter: {
        searchTerm: "simulation"
        type: TEXT_SEARCH
        language: "en"
      }
    ) {
      items {
        rtId
        name
        description
      }
    }
  }
}

Supported languages

The language parameter accepts standard language codes. Common values include:

Code	Language
en	English
de	German
fr	French
es	Spanish
it	Italian

Configuring text index

To use TEXT_SEARCH mode, the entity type must have a text index configured in the Construction Kit. This is done by setting indexType=Text on the relevant attributes.

SearchFilter structure

Field	Type	Required	Description
searchTerm	String	Yes	The text to search for
type	SearchFilterType	Yes	Either ATTRIBUTE_FILTER or TEXT_SEARCH
attributePaths	[String]	For ATTRIBUTE_FILTER	List of attribute paths to search in
language	String	For TEXT_SEARCH	Language code for full-text search

SearchFilter vs FieldFilter

Feature	SearchFilter	FieldFilter
Purpose	Text search across multiple attributes	Precise filtering on single attribute
Data types	Optimized for text/strings	Works with all types (text, numbers, booleans, etc.)
Match type	Wildcard or full-text	Exact match or operator-based
Use case	Search boxes in UI	Data filtering, state checks

When to use SearchFilter

• Search input fields in list views
• User-facing free-text search
• Searching across multiple text attributes simultaneously

When to use FieldFilter

• Filtering by specific values (e.g., state = "ON")
• Numeric comparisons (e.g., voltage > 220)
• Boolean checks
• Enum value filtering

Combining with other parameters

SearchFilter can be combined with fieldFilter, sortOrder, and pagination:

query getAdapters(
  $after: String
  $first: Int
  $searchFilter: SearchFilter
  $fieldFilters: [FieldFilter]
  $sort: [Sort]
) {
  runtime {
    systemCommunicationAdapter(
      after: $after
      first: $first
      searchFilter: $searchFilter
      fieldFilter: $fieldFilters
      sortOrder: $sort
    ) {
      pageInfo {
        endCursor
        hasNextPage
      }
      totalCount
      items {
        rtId
        name
        description
        deploymentState
      }
    }
  }
}

Variables:

{
  "first": 20,
  "searchFilter": {
    "searchTerm": "production",
    "type": "ATTRIBUTE_FILTER",
    "attributePaths": ["name", "description"]
  },
  "fieldFilters": [
    { "attributePath": "deploymentState", "operator": "EQUALS", "comparisonValue": "DEPLOYED" }
  ],
  "sort": [
    { "attributePath": "name", "sortOrder": "ASCENDING" }
  ]
}

This query:

1. Searches for "production" in name and description
2. Filters only deployed adapters
3. Sorts results by name
4. Returns first 20 results with pagination

Best practices

1. Choose the right mode: Use ATTRIBUTE_FILTER for simple searches, TEXT_SEARCH when full-text indexing is available
2. Limit attribute paths: Only include attributes that are relevant for searching to improve performance
3. Combine with pagination: Always use pagination with search to handle large result sets
4. Use FieldFilter for non-text data: SearchFilter is not designed for searching integers, booleans, or dates
5. Set up text indexes: For frequently searched entity types, configure text indexes in the Construction Kit for better performance with TEXT_SEARCH mode