# Search

Search for messages, files, and content across the Slack workspace with flexible query options. The Search API provides powerful search capabilities similar to Slack's built-in search functionality.

## Capabilities

### Search All

Search for both messages and files matching a query across the workspace.

```typescript { .api }
/**
 * Search for messages and files matching a query
 * @param options - Search parameters with query and options
 * @returns Promise resolving to combined search results
 */
search.all(options: SearchAllArguments): Promise<SearchAllResponse>;

interface SearchAllArguments extends TokenOverridable, TraditionalPagingEnabled, Searchable {}

interface Searchable extends OptionalTeamAssignable, SortDir {
  /** Search query string */
  query: string;
  /** Enable query highlight markers (default: false) */
  highlight?: boolean;
  /** Sort results by 'score' or 'timestamp' (default: 'score') */
  sort?: 'score' | 'timestamp';
}

interface SearchAllResponse extends WebAPICallResult {
  /** Combined search results */
  messages?: SearchMessageResults;
  files?: SearchFileResults;
  /** Search query that was executed */
  query?: string;
}
```

**Usage Examples:**

```typescript
import { WebClient } from "@slack/web-api";

const web = new WebClient(process.env.SLACK_BOT_TOKEN);

// Search for messages and files containing "project update"
const results = await web.search.all({
  query: "project update",
  sort: "timestamp",
  highlight: true
});

// Search with pagination
const page1 = await web.search.all({
  query: "bug report",
  count: 20,
  page: 1
});
```

### Search Files

Search specifically for files matching a query.

```typescript { .api }
/**
 * Search for files matching a query  
 * @param options - Search parameters with query and options
 * @returns Promise resolving to file search results
 */
search.files(options: SearchFilesArguments): Promise<SearchFilesResponse>;

interface SearchFilesArguments extends TokenOverridable, TraditionalPagingEnabled, Searchable {}

interface SearchFilesResponse extends WebAPICallResult {
  /** File search results */
  files?: SearchFileResults;
  /** Search query that was executed */
  query?: string;
}

interface SearchFileResults {
  /** Total number of files found */
  total?: number;
  /** Pagination information */
  paging?: SearchPaging;
  /** Array of matching files */
  matches?: FileMatch[];
}

interface FileMatch {
  /** File object */
  file?: File;
  /** Search score */
  score?: number;
  /** Highlighted preview text */
  preview?: string;
  /** Highlighted preview (HTML) */
  preview_highlight?: string;
}
```

### Search Messages

Search specifically for messages matching a query.

```typescript { .api }
/**
 * Search for messages matching a query
 * @param options - Search parameters with query and options  
 * @returns Promise resolving to message search results
 */
search.messages(options: SearchMessagesArguments): Promise<SearchMessagesResponse>;

interface SearchMessagesArguments extends TokenOverridable, TraditionalPagingEnabled, Searchable {}

interface SearchMessagesResponse extends WebAPICallResult {
  /** Message search results */
  messages?: SearchMessageResults;
  /** Search query that was executed */  
  query?: string;
}

interface SearchMessageResults {
  /** Total number of messages found */
  total?: number;
  /** Pagination information */
  paging?: SearchPaging;
  /** Array of matching messages */
  matches?: MessageMatch[];
}

interface MessageMatch {
  /** Message object */
  message?: Message;
  /** Search score */
  score?: number; 
  /** Channel information */
  channel?: {
    id?: string;
    name?: string;
    is_channel?: boolean;
    is_group?: boolean;
    is_im?: boolean;
    is_mpim?: boolean;
  };
  /** Message type */
  type?: string;
  /** User who sent the message */
  user?: string;
  /** Username who sent the message */
  username?: string;
  /** Timestamp of the message */
  ts?: string;
  /** Message text with highlights */
  text?: string;
  /** Previous message context */
  previous?: MessageContext;
  /** Next message context */
  next?: MessageContext;
}

interface MessageContext {
  /** Context message user */
  user?: string;
  /** Context message username */
  username?: string;
  /** Context message text */
  text?: string;
  /** Context message timestamp */
  ts?: string;
  /** Context message type */
  type?: string;
}
```

**Usage Examples:**

```typescript
// Search for messages containing specific keywords
const messageResults = await web.search.messages({
  query: "quarterly review",
  highlight: true,
  sort: "timestamp" 
});

// Search for files with specific types
const fileResults = await web.search.files({
  query: "filetype:pdf budget",
  count: 10
});

// Advanced query examples
const advancedSearch = await web.search.messages({
  query: "from:@john in:#general has:link after:2024-01-01",
  highlight: true
});
```

## Query Syntax

Slack search supports rich query syntax:

- **Basic text**: `project update`
- **From user**: `from:@username` or `from:me`
- **In channel**: `in:#channel` or `in:@username`
- **Date ranges**: `after:2024-01-01`, `before:2024-12-31`, `during:January`
- **File types**: `filetype:pdf`, `filetype:image`
- **Has attachments**: `has:link`, `has:attachment`
- **Exclude terms**: `-word` to exclude specific terms
- **Phrases**: `"exact phrase"` for exact matches

## Pagination

All search methods support traditional pagination:

```typescript
interface SearchPaging {
  /** Current page number */
  page?: number;
  /** Total number of pages */
  pages?: number;
  /** Items per page */
  count?: number;
  /** Total number of results */
  total?: number;
  /** Start index for current page */
  first?: number;
  /** End index for current page */  
  last?: number;
}

// Paginated search example
const searchPage = async (query: string, page: number) => {
  return await web.search.messages({
    query,
    page,
    count: 20
  });
};
```

## Core Types

```typescript { .api }
interface SortDir {
  /** Sort direction - 'asc' or 'desc' (default: 'desc') */
  sort_dir?: 'asc' | 'desc';
}

interface OptionalTeamAssignable {
  /** Team ID for Enterprise Grid workspaces */
  team_id?: string;
}

interface TraditionalPagingEnabled {
  /** Number of items to return per page */
  count?: number;
  /** Page number for pagination */
  page?: number;
}

interface TokenOverridable {
  /** Override the default token for this request */
  token?: string;
}
```