Skip to main content

Your First Query

Learn how to ingest a repository and perform your first semantic code search in 60 seconds.

Step 1: Ingest a Repository​

Start by ingesting a public repository. Let's use the NestJS framework as an example:

curl -X POST http://localhost:3000/ingestions/repository \
  -H "Content-Type: application/json" \
  -d '{
    "repoUrl": "https://github.com/nestjs/nest.git",
    "ref": "master"
  }'

Response:

{
  "status": "queued",
  "jobId": "01HQZX3Y4Z5A6B7C8D9E0F1G2H",
  "repoUrl": "https://github.com/nestjs/nest.git",
  "ref": "master",
  "repoId": "nest"
}
Auto-deduced repoId

The repoId is automatically extracted from the repository URL if not provided. For example:

  • https://github.com/nestjs/nest.git → repoId: "nest"

Step 2: Check Ingestion Status​

Monitor the ingestion progress using the job ID:

curl http://localhost:3000/jobs/job/01HQZX3Y4Z5A6B7C8D9E0F1G2H

Response (processing):

{
  "id": "01HQZX3Y4Z5A6B7C8D9E0F1G2H",
  "state": "active",
  "progress": 45,
  "data": {
    "repoUrl": "https://github.com/nestjs/nest.git",
    "ref": "master"
  }
}

Wait until state becomes "completed" before searching.

Step 3: Search Your Codebase​

Once ingestion is complete, perform a semantic search. Note: repoId is required in the URL path.

curl -X POST http://localhost:3000/queries/search/nest \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "How do I create a custom decorator?",
    "k": 5
  }'

Response:

{
  "results": [
    {
      "id": "packages/common/decorators/custom.decorator.ts",
      "content": "export function CustomDecorator() {\n  return (target: any) => { ... }\n}",
      "repoId": "nest",
      "metadata": { "category": "repository" }
    }
  ]
}

Understanding the Results​

Rephole returns an array of matching chunks with structured data:

FieldDescription
idFile path (e.g., src/auth/auth.service.ts)
contentFull file content
repoIdRepository identifier
metadataCustom metadata from ingestion

Key Features​

  • Semantic Search: Find code by meaning, not just keywords
  • Parent-Child Retrieval: Search small chunks, return full file context
  • Natural Language: Ask questions like you would to a colleague
  • Metadata Filtering: Filter results by custom tags

Try More Queries​

# Find authentication implementations
curl -X POST http://localhost:3000/queries/search/nest \
  -H "Content-Type: application/json" \
  -d '{"prompt": "How does authentication work?", "k": 3}'

# Find error handling patterns
curl -X POST http://localhost:3000/queries/search/nest \
  -H "Content-Type: application/json" \
  -d '{"prompt": "How are errors handled and thrown?", "k": 5}'

Next Steps​