> ## Documentation Index
> Fetch the complete documentation index at: https://social-b97141fb-feat-user-history-moderation-detail.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & Discovery

> Add semantic and hashtag post search, community search, trending communities, content recommendations, and category browsing.

> [!NOTE]
>
> **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**
>
> ```typescript theme={null}
> // 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 ↓

> [!TIP]
>
> **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.

```mermaid theme={null}
graph TD
    A[User wants to find content] --> B{Discovery method}
    B -->|Search bar| C[Intelligent Search]
    B -->|Explore tab| D[Trending Communities]
    B -->|Category browse| E[Community Categories]
    B -->|Algorithm-driven| F[Recommended Communities]
    C --> G[Search posts]
    C --> H[Search communities]
    D & E & F --> I[Community cards]
    G & H & I --> J[User navigates to content]

    classDef action fill:#e1f5fe,stroke:#0288d1,color:#01579b
    classDef decision fill:#fff8e1,stroke:#f9a825,color:#f57f17
    classDef process fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    classDef outcome fill:#e8f5e9,stroke:#388e3c,color:#1b5e20

    class A action
    class B decision
    class C,D,E,F,G,H,I process
    class J outcome
```

> [!NOTE]
>
> **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.

> [!NOTE]
>
> **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:

```typescript TypeScript theme={null}
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 */ }
  },
);
```

```dart Flutter theme={null}
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](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-community.md)

***

## Step-by-Step Implementation

**1. 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.

```typescript TypeScript theme={null}
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 */ }
  },
);
```

```dart Flutter theme={null}
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](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-community.md)

**2. Get trending communities**

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

```typescript TypeScript theme={null}
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](/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities.md)

**3. Get recommended communities**

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

```typescript TypeScript theme={null}
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](/social-plus-sdk/social/communities-spaces/discovery/trending-and-recommended-communities.md)

**4. Browse communities by category**

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

```typescript TypeScript theme={null}
import { CategoryRepository } from '@amityco/ts-sdk';

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

Full reference → [Community Categories](/social-plus-sdk/social/communities-spaces/organization/community-categories.md) · [Query Communities](/social-plus-sdk/social/communities-spaces/discovery/query-communities.md)

**5. 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`.

```typescript TypeScript theme={null}
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();
```

```dart Flutter theme={null}
// 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](/social-plus-sdk/social/discovery-engagement/search/intelligent-search-post.md)

***

## 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](/analytics-and-moderation/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](/analytics-and-moderation/console/product-management/overview.md)

***

## Common Mistakes

> [!WARNING]
>
> **Firing a search API call on every keystroke** — This creates excessive API calls and flickers results. Debounce the input by 300–500ms before searching.
>
> ```typescript theme={null}
> // ❌ 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)} />
> ```

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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

***

> [!TIP]
>
> **Dive deeper**: [Discovery & Engagement API Reference](/social-plus-sdk/social/discovery-engagement/overview.md) 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](/use-cases/social/user-search-and-people-discovery.md)**
>
> Content search is working — now let users find each other with people search and suggestions.

Or explore related guides:

> **[Community Platform](/use-cases/social/community-platform.md)**
>
> Build the communities that discovery surfaces

> **[Build a Social Feed](/use-cases/social/build-a-social-feed.md)**
>
> Show content from discovered communities in a feed

> **[Notifications & Engagement](/use-cases/social/notifications-and-engagement.md)**
>
> Notify users about trending content they'd be interested in


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.