# Retrieval

## Retrieve

`client.Beta.Retrieval.Get(ctx, params) (*BetaRetrievalGetResponse, error)`

**post** `/api/v1/retrieval/retrieve`

Retrieve relevant chunks via hybrid search (vector + full-text), with filtering on built-in or user-defined metadata.

### Parameters

- `params BetaRetrievalGetParams`

  - `IndexID param.Field[string]`

    Body param: ID of the index to retrieve against.

  - `Query param.Field[string]`

    Body param: Natural-language query to retrieve relevant chunks.

  - `OrganizationID param.Field[string]`

    Query param

  - `ProjectID param.Field[string]`

    Query param

  - `CustomFilters param.Field[map[string, BetaRetrievalGetParamsCustomFilterUnion]]`

    Body param: Filters on user-defined metadata fields.

    - `type BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloat struct{…}`

      - `Operator string`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorEq BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "eq"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorNe BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "ne"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorGt BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "gt"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorLt BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "lt"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorGte BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "gte"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorLte BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "lte"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorIn BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "in"`

        - `const BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperatorNin BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatOperator = "nin"`

      - `Value BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatValueUnion`

        - `string`

        - `bool`

        - `float64`

        - `type BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatValueArray []BetaRetrievalGetParamsCustomFilterFilterTypeUnionStrIntBoolFloatValueArrayItemUnion`

          - `string`

          - `bool`

          - `float64`

    - `type BetaRetrievalGetParamsCustomFilterArray []BetaRetrievalGetParamsCustomFilterArrayItem`

      - `Operator string`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorEq BetaRetrievalGetParamsCustomFilterArrayItemOperator = "eq"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorNe BetaRetrievalGetParamsCustomFilterArrayItemOperator = "ne"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorGt BetaRetrievalGetParamsCustomFilterArrayItemOperator = "gt"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorLt BetaRetrievalGetParamsCustomFilterArrayItemOperator = "lt"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorGte BetaRetrievalGetParamsCustomFilterArrayItemOperator = "gte"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorLte BetaRetrievalGetParamsCustomFilterArrayItemOperator = "lte"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorIn BetaRetrievalGetParamsCustomFilterArrayItemOperator = "in"`

        - `const BetaRetrievalGetParamsCustomFilterArrayItemOperatorNin BetaRetrievalGetParamsCustomFilterArrayItemOperator = "nin"`

      - `Value BetaRetrievalGetParamsCustomFilterArrayItemValueUnion`

        - `float64`

        - `type BetaRetrievalGetParamsCustomFilterArrayItemValueArray []float64`

  - `FullTextPipelineWeight param.Field[float64]`

    Body param: Weight of the full-text search pipeline (0-1).

  - `NumCandidates param.Field[int64]`

    Body param: Number of candidates for approximate nearest neighbor search.

  - `Rerank param.Field[BetaRetrievalGetParamsRerank]`

    Body param: Reranking configuration applied after hybrid search. Enabled by default.

    - `Enabled bool`

      Set to false to disable reranking.

    - `TopN int64`

      Number of results to return after reranking.

  - `ScoreThreshold param.Field[float64]`

    Body param: Minimum score threshold for returned results.

  - `StaticFilters param.Field[BetaRetrievalGetParamsStaticFilters]`

    Body param: Filters on built-in document fields (page range, chunk index, etc.).

    - `ParsedDirectoryFileID BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileID`

      - `Operator string`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorEq BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "eq"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorNe BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "ne"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorGt BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "gt"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorLt BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "lt"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorGte BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "gte"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorLte BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "lte"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorIn BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "in"`

        - `const BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperatorNin BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDOperator = "nin"`

      - `Value BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDValueUnion`

        - `string`

        - `type BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDValueArray []string`

  - `TopK param.Field[int64]`

    Body param: Maximum number of results to return.

  - `VectorPipelineWeight param.Field[float64]`

    Body param: Weight of the vector search pipeline (0-1).

### Returns

- `type BetaRetrievalGetResponse struct{…}`

  Response containing retrieval results.

  - `Results []BetaRetrievalGetResponseResult`

    Ordered list of retrieved chunks.

    - `Content string`

      Text content of the retrieved chunk.

    - `Metadata map[string, BetaRetrievalGetResponseResultMetadataUnion]`

      User-defined metadata associated with the chunk.

      - `string`

      - `float64`

      - `bool`

      - `type BetaRetrievalGetResponseResultMetadataArray []string`

    - `RerankScore float64`

      Relevance score from the reranker, if reranking was applied.

    - `Score float64`

      Hybrid search relevance score.

    - `StaticFields BetaRetrievalGetResponseResultStaticFields`

      Built-in fields stored for every exported chunk.

      - `Attachments []BetaRetrievalGetResponseResultStaticFieldsAttachment`

        Attachments associated with the chunk

        - `AttachmentName string`

          Attachment-relative path, e.g. 'screenshots/page_7.jpg'.

        - `SourceID string`

          File ID to pass as source_id when fetching the attachment.

        - `Type string`

          Attachment kind, e.g. 'screenshot', 'items'.

      - `ChunkEndChar int64`

        End character offset of the chunk.

      - `ChunkIndex int64`

        Index of the chunk within the file.

      - `ChunkStartChar int64`

        Start character offset of the chunk.

      - `ChunkTokenCount int64`

        Token count of the chunk.

      - `PageRangeEnd int64`

        Last page number covered by this chunk.

      - `PageRangeStart int64`

        First page number covered by this chunk.

      - `ParsedDirectoryFileID string`

        ID of the parsed file.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/llamacloud-prod-go"
  "github.com/stainless-sdks/llamacloud-prod-go/option"
)

func main() {
  client := llamacloudprod.NewClient(
    option.WithAPIKey("My API Key"),
  )
  retrieval, err := client.Beta.Retrieval.Get(context.TODO(), llamacloudprod.BetaRetrievalGetParams{
    IndexID: "idx-abc123",
    Query: "What are the key findings?",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", retrieval.Results)
}
```

#### Response

```json
{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}
```

## Search Files

`client.Beta.Retrieval.Search(ctx, params) (*BetaRetrievalSearchResponse, error)`

**post** `/api/v1/retrieval/files/search`

Search for files by name.

### Parameters

- `params BetaRetrievalSearchParams`

  - `IndexID param.Field[string]`

    Body param: ID of the index to search within.

  - `OrganizationID param.Field[string]`

    Query param

  - `ProjectID param.Field[string]`

    Query param

  - `FileName param.Field[string]`

    Body param: Exact file name to match.

  - `FileNameContains param.Field[string]`

    Body param: Substring match on file name (case-insensitive).

  - `Limit param.Field[int64]`

    Body param: Maximum number of files to return.

### Returns

- `type BetaRetrievalSearchResponse struct{…}`

  File search results.

  - `Files []BetaRetrievalSearchResponseFile`

    Matching files with names.

    - `FileID string`

      ID of the file.

    - `FileName string`

      Display name of the file.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/llamacloud-prod-go"
  "github.com/stainless-sdks/llamacloud-prod-go/option"
)

func main() {
  client := llamacloudprod.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.Beta.Retrieval.Search(context.TODO(), llamacloudprod.BetaRetrievalSearchParams{
    IndexID: "idx-abc123",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Files)
}
```

#### Response

```json
{
  "files": [
    {
      "file_id": "file_id",
      "file_name": "file_name"
    }
  ]
}
```

## Grep File

`client.Beta.Retrieval.Grep(ctx, params) (*BetaRetrievalGrepResponse, error)`

**post** `/api/v1/retrieval/files/grep`

Grep within a file's parsed content using a regex pattern.

### Parameters

- `params BetaRetrievalGrepParams`

  - `FileID param.Field[string]`

    Body param: ID of the file to grep.

  - `IndexID param.Field[string]`

    Body param: ID of the index the file belongs to.

  - `Pattern param.Field[string]`

    Body param: Regex pattern to search for.

  - `OrganizationID param.Field[string]`

    Query param

  - `ProjectID param.Field[string]`

    Query param

  - `ContextChars param.Field[int64]`

    Body param: Number of characters of context to include before and after the matched pattern in the content field of the response

  - `Limit param.Field[int64]`

    Body param: Maximum number of matches to return.

### Returns

- `type BetaRetrievalGrepResponse struct{…}`

  Grep results for a file.

  - `Matches []BetaRetrievalGrepResponseMatch`

    Regex matches found in the file.

    - `Content string`

      Matched text content.

    - `EndChar int64`

      End character offset of the match.

    - `StartChar int64`

      Start character offset of the match.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/llamacloud-prod-go"
  "github.com/stainless-sdks/llamacloud-prod-go/option"
)

func main() {
  client := llamacloudprod.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.Beta.Retrieval.Grep(context.TODO(), llamacloudprod.BetaRetrievalGrepParams{
    FileID: "file_id",
    IndexID: "idx-abc123",
    Pattern: "revenue|profit",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Matches)
}
```

#### Response

```json
{
  "matches": [
    {
      "content": "content",
      "end_char": 0,
      "start_char": 0
    }
  ]
}
```

## Read File

`client.Beta.Retrieval.Read(ctx, params) (*BetaRetrievalReadResponse, error)`

**post** `/api/v1/retrieval/files/read`

Read the parsed text content of a specific file.

### Parameters

- `params BetaRetrievalReadParams`

  - `FileID param.Field[string]`

    Body param: ID of the file to read.

  - `IndexID param.Field[string]`

    Body param: ID of the index the file belongs to.

  - `OrganizationID param.Field[string]`

    Query param

  - `ProjectID param.Field[string]`

    Query param

  - `MaxLength param.Field[int64]`

    Body param: Maximum number of characters to read from the offset.

  - `Offset param.Field[int64]`

    Body param: Starting character offset.

### Returns

- `type BetaRetrievalReadResponse struct{…}`

  File read result.

  - `Content string`

    Parsed text content of the file.

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/llamacloud-prod-go"
  "github.com/stainless-sdks/llamacloud-prod-go/option"
)

func main() {
  client := llamacloudprod.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.Beta.Retrieval.Read(context.TODO(), llamacloudprod.BetaRetrievalReadParams{
    FileID: "file_id",
    IndexID: "idx-abc123",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Content)
}
```

#### Response

```json
{
  "content": "content"
}
```