Search & Discovery

SDK v7.x · Flutter semantic search requires amity_sdk 7.8.7+ · Last verified August 2026 · iOS · Android · Web · Flutter

Speed run — just the code

// 1. Semantic search for communities
CommunityRepository.semanticSearchCommunities(
  { query: 'gaming', limit: 10 },
  ({ data }) => { renderResults(data); }
);

// 2a. Semantic (AI) search for posts
PostRepository.semanticSearchPosts(
  { query: 'healthy recipes', dataTypes: ['text', 'image'], limit: 20 },
  ({ data }) => { renderResults(data); }
);

// 2b. Hashtag search for posts
PostRepository.searchPostsByHashtag(
  { hashtags: ['recipe'], limit: 20 },
  ({ data }) => { renderResults(data); }
);

// 3. Get trending communities
CommunityRepository.getTrendingCommunities(
  { limit: 10 },
  ({ data }) => { renderTrending(data); }
);

Full walkthrough below ↓

Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step. One exception: hashtag post search (searchPostsByHashtag) is not available in the Flutter SDK.

Discovery turns a closed social app into a growing platform. This guide walks through implementing semantic and hashtag search for posts, semantic search for communities, surfacing trending content, and building a category-based browsing experience.

Prerequisites: SDK installed and authenticated. By default, search returns public communities. Semantic community search can also include discoverable private communities when includeDiscoverablePrivateCommunity: true; hidden private communities remain excluded.

After completing this guide you’ll have:

Semantic and hashtag post search integrated into your app’s search bar
Community search with trending and recommended community lists
User-facing category browsing connected to community filtering

Quick Start: Search Communities

Community search is the primary discovery surface — use a semantic query with optional membership, tag, category, and discoverable-private filters:

import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.semanticSearchCommunities(
  {
    query: 'gaming',
    communityMembershipStatus: AmityCommunityMemberStatusFilter.ALL,
  },
  ({ data: communities, onNextPage, hasNextPage, loading }) => {
    if (communities) { /* render community search results */ }
  },
);

final liveCollection = AmitySocialClient.newCommunityRepository()
    .semanticSearchCommunities(
      query: 'gaming',
      filter: AmityCommunityFilter.ALL,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((communities) {
  // Render communities in your UI.
});
await liveCollection.loadNext();

Full reference → Intelligent Search: Communities

Step-by-Step Implementation

Search communities

Search communities with optional membership status (all, member, notMember), tags, discoverable-private, and category filters. Semantic results are ordered by backend relevance; use regular getCommunities() when you need an explicit sort order.

import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.semanticSearchCommunities(
  { query: 'game', communityMembershipStatus: AmityCommunityMemberStatusFilter.ALL },
  ({ data: communities, onNextPage, hasNextPage, loading }) => {
    if (communities) { /* render community results */ }
  },
);

final liveCollection = AmitySocialClient.newCommunityRepository()
    .semanticSearchCommunities(
      query: 'game',
      filter: AmityCommunityFilter.ALL,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((communities) {
  // Render communities in your UI.
});
await liveCollection.loadNext();

Full reference → Intelligent Search: Communities

Get trending communities

Trending communities are ranked by recent activity (posts, members, engagement). Surface these on your explore page for new users.

TypeScript

import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getTrendingCommunities(
  { limit: 5 },
  ({ data: communities, loading }) => {
    if (communities) { /* render trending section */ }
  },
);

Full reference → Trending & Recommended Communities

Get recommended communities

Recommended communities are personalized for the current user based on their activity and interests. Returns up to 15 communities.

TypeScript

import { CommunityRepository } from '@amityco/ts-sdk';

const unsubscriber = CommunityRepository.getRecommendedCommunities(
  { limit: 5, includeDiscoverablePrivateCommunity: true },
  ({ data: communities, loading }) => {
    if (communities) { /* render recommended section */ }
  },
);

Full reference → Trending & Recommended Communities

Browse communities by category

Organize communities into browsable categories. Query all categories, then filter communities by a selected category.

TypeScript

import { CategoryRepository } from '@amityco/ts-sdk';

const unsubscriber = CategoryRepository.getCategories(
  {},
  ({ data: categories, loading }) => {
    if (categories) { /* render category filter pills */ }
  },
);

Full reference → Community Categories · Query Communities

Search posts

Two complementary search methods are available for posts:

Semantic search (PostRepository.semanticSearchPosts) — AI-powered natural-language search. Best for open-ended queries like “healthy breakfast ideas”.
Hashtag search (PostRepository.searchPostsByHashtag) — exact hashtag matching. Best for tag-driven browsing like #recipe.

import { PostRepository } from '@amityco/ts-sdk';

const semanticSearchUnsubscriber = PostRepository.semanticSearchPosts(
  {
    query: 'healthy breakfast ideas',
    targetId: communityId,
    targetType: 'community',
    dataTypes: ['text', 'image'],
    matchingOnlyParentPost: true,
    limit: 20,
  },
  ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(posts);

    if (hasNextPage) {
      onNextPage?.();
    }
  },
);

const hashtagSearchUnsubscriber = PostRepository.searchPostsByHashtag(
  {
    targetType: 'community',
    hashtags: ['recipe'],
    dataTypes: ['image'],
    matchingOnlyParentPost: true,
    limit: 20,
  },
  ({ data: posts, loading, error }) => {
    if (loading) return;
    if (error) {
      handleError(error);
      return;
    }

    renderResults(posts);
  },
);

semanticSearchUnsubscriber();
hashtagSearchUnsubscriber();

// Flutter exposes semantic post search only; hashtag search is not available.
final liveCollection = AmitySocialClient.newPostRepository()
    .semanticSearchPosts(
      query: 'healthy breakfast ideas',
      targetType: AmityPostTargetType.COMMUNITY,
      targetId: communityId,
      postTypes: const [AmityDataType.TEXT, AmityDataType.IMAGE],
      matchingOnlyParentPosts: true,
    )
    .getLiveCollection(pageSize: 20);

liveCollection.getStreamController().stream.listen((posts) {
  // Render posts in your UI.
});
await liveCollection.loadNext();

Full reference → Intelligent Search: Posts

Connect to Moderation & Analytics

Analytics: search usage

Track search query volume and discovery patterns in Admin Console → Analytics Dashboard → Social Insights to understand what users are looking for and which communities are growing.→ Admin Console: Analytics

Admin: category management

Create and manage community categories in the Admin Console. Categories appear in the community creation flow and in the discovery browse view.→ Admin Console: Product Management

Common Mistakes

Firing a search API call on every keystroke — This creates excessive API calls and flickers results. Debounce the input by 300–500ms before searching.

// ❌ Bad — search on every key
<input onChange={(e) => search(e.target.value)} />

// ✅ Good — debounce
const debouncedSearch = useMemo(
  () => debounce((q) => search(q), 400), []
);
<input onChange={(e) => debouncedSearch(e.target.value)} />

Not handling empty search results — “No results found” is not enough. Suggest alternative queries, show trending content, or recommend popular communities to keep users engaged.

Searching without a minimum query length — Single-character searches return too many results and waste resources. Require at least 2–3 characters before triggering a search.

Best Practices

Search UX

Add a 300ms debounce to search input before firing the query — prevents excessive API calls while the user types
Show suggested/recent searches before the user starts typing
Display skeleton placeholders while results load
Clearly differentiate post results from community results with distinct card styles
Show a “No results” empty state with suggestions if the query returns 0 results

Explore/Discover UX

Show trending communities prominently for logged-in users with no following history
Once a user has joined 5+ communities, replace trending with personalized recommendations
Use horizontal scrolling category pills for browsing — they take less vertical space than a list
Cache trending and recommended results for 5-10 minutes — they don’t need to be real-time

Performance

Use searchPosts() Live Collection — this handles debounced re-querying automatically on most platforms
Limit search result sets to 20-30 items; use pagination for deeper results
Pre-load categories at app launch and cache locally — they change infrequently

Dive deeper: Discovery & Engagement API Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

Next Steps

Your next step → User Search & People Discovery

Content search is working — now let users find each other with people search and suggestions.

Or explore related guides:

Community Platform

Build the communities that discovery surfaces

Build a Social Feed

Show content from discovered communities in a feed

Notifications & Engagement

Notify users about trending content they’d be interested in

Overview

Build Your Community

Create & Share Content

Communication

Engage & Grow

Livestream

Monetize

Quick Start: Search Communities

Step-by-Step Implementation

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps

Your next step → User Search & People Discovery

Community Platform

Build a Social Feed

Notifications & Engagement

​Quick Start: Search Communities

​Step-by-Step Implementation

​Connect to Moderation & Analytics

​Common Mistakes

​Best Practices

​Next Steps

Your next step → User Search & People Discovery

Community Platform

Build a Social Feed

Notifications & Engagement

Quick Start: Search Communities

Step-by-Step Implementation

Connect to Moderation & Analytics

Common Mistakes

Best Practices

Next Steps