vybekiit 0.4.0 → 0.6.0

package/dist/global-skills/firebase-data-connect/reference/search.md

@@ -0,0 +1,264 @@
+# Search Solutions Reference (Vector & Full-Text Search)
+
+Use this reference to design, configure, and implement search capabilities in
+SQL Connect. SQL Connect supports three types of search:
+
+1. **Vector Similarity Search (Semantic)**: Best for finding
+   conceptually/semantically similar rows (e.g., recommendations, "more like
+   this"). Requires Vertex AI.
+1. **Full-Text Search (Lexical)**: Best for keyword and phrase search across
+   single or multiple columns. Supports lexical stemming.
+1. **String Pattern Filters (Exact/Regex)**: Best for simple prefix, exact
+   match, or basic wildcard queries (uses standard Postgres indexing).
+
+______________________________________________________________________
+
+## Search Selection Guide
+
+Use this comparative guide to choose the optimal search strategy for the user's
+task:
+
+| Feature / Capability | Vector Similarity Search                            | Full-Text Search                               | String Pattern Filters                                 |
+| :------------------- | :-------------------------------------------------- | :--------------------------------------------- | :----------------------------------------------------- |
+| **Use Case**         | Semantic search, recommendations, RAG pipelines.    | Keyword search, parsing large text fields.     | Exact matches, regular expressions, simple wildcards.  |
+| **Engine Support**   | Vertex AI Embeddings + `pgvector` extension.        | Native PostgreSQL full-text engine.            | Native PostgreSQL indexing (`LIKE`, `ILIKE`).          |
+| **Matching Style**   | Semantic/concept proximity.                         | Lexical stemming (tenses, root words).         | Exact character sequence.                              |
+| **Column Support**   | Single column per query.                            | Multiple columns combined.                     | Multiple columns via standard logical filters (`_or`). |
+| **Overhead**         | High (API execution costs & vector column storage). | Medium (generates indices & tsvector columns). | Low (uses standard index / minimal storage).           |
+
+______________________________________________________________________
+
+## 1. Vector Similarity Search (Semantic)
+
+Perform semantic matching by generating vector embeddings representing the
+semantic meaning of text.
+
+### Schema Setup
+
+- **Configure Column Dimensions**: Define the column dimension size using the
+  `@col(size: X)` directive — SQL Connect requires an explicit size for Vector
+  fields to allocate storage.
+- **Match Model Specifications**: Ensure the column size matches the output
+  dimension of your chosen embedding model (e.g., **768** for Google Vertex AI's
+  `textembedding-gecko` models) to prevent runtime type mismatches.
+
+```graphql
+type Movie @table {
+  id: UUID! @default(expr: "uuidV4()")
+  title: String!
+  description: String
+  # Vector field for description embeddings (Vertex AI gecko size is 768)
+  descriptionEmbedding: Vector! @col(size: 768)
+}
+```
+
+### Automatic Embedding Generation (`_embed` server value)
+
+Ensure you use the exact same embedding model across all queries and mutations
+on a given vector field — vector embeddings generated from different model
+versions are incompatible and will result in poor search relevance or errors.
+
+#### A. Generation on Insert
+
+Use the `${vectorFieldName}_embed` input parameter to automatically generate and
+store embeddings on creation.
+
+```graphql
+# connector/mutations.gql
+mutation CreateMovieWithEmbedding($title: String!, $description: String!) @auth(level: USER) {
+  movie_insert(data: {
+    title: $title,
+    description: $description,
+    descriptionEmbedding_embed: {
+      model: "textembedding-gecko@003",
+      text: $description
+    }
+  })
+}
+```
+
+#### B. Generation on Update
+
+```graphql
+# connector/mutations.gql
+mutation UpdateMovieDescription($id: UUID!, $description: String!) @auth(level: USER) {
+  movie_update(
+    id: $id,
+    data: {
+      description: $description,
+      descriptionEmbedding_embed: {
+        model: "textembedding-gecko@003",
+        text: $description
+      }
+    }
+  )
+}
+```
+
+### Similarity Search Queries
+
+SQL Connect automatically generates a similarity query function for every
+`Vector` field in the format: `${pluralType}_${vectorFieldName}_similarity`
+
+#### A. Auto-Embedding Search
+
+Use `compare_embed` to automatically convert the search query string into an
+embedding on the fly using Vertex AI.
+
+```graphql
+# connector/queries.gql
+query SearchMoviesByDescription($query: String!) @auth(level: PUBLIC) {
+  movies_descriptionEmbedding_similarity(
+    compare_embed: { model: "textembedding-gecko@003", text: $query },
+    limit: 5
+  ) {
+    id
+    title
+    description
+  }
+}
+```
+
+#### B. Custom Vector Search
+
+Use `compare` to pass raw pre-computed float arrays (cast as a `Vector!`)
+directly to the search without calling Vertex AI.
+
+```graphql
+# connector/queries.gql
+query SearchMoviesByCustomVector($vector: Vector!, $limit: Int!) @auth(level: PUBLIC) {
+  movies_descriptionEmbedding_similarity(
+    compare: $vector,
+    method: L2,
+    limit: $limit
+  ) {
+    id
+    title
+  }
+}
+```
+
+### Tuning Vector Proximity
+
+- **Distance Thresholding**: Select the `_metadata { distance }` field to
+  evaluate how close the results are, then define a tight threshold using the
+  `within` parameter.
+- **Distance Metric Gotcha**: `L2` and `COSINE` return different distance
+  scales. Re-tune your `within` threshold if you change the `method` parameter,
+  as their distance ranges are not compatible.
+
+```graphql
+# connector/queries.gql
+query SearchMoviesCosineSimilarity($query: String!) @auth(level: PUBLIC) {
+  movies_descriptionEmbedding_similarity(
+    compare_embed: { model: "textembedding-gecko@003", text: $query },
+    method: COSINE,
+    within: 0.5, # Maximum distance threshold
+    limit: 5
+  ) {
+    id
+    title
+    _metadata { distance }
+  }
+}
+```
+
+______________________________________________________________________
+
+## 2. Full-Text Search (Lexical)
+
+Perform fast, stemmed keyword/phrase searches over single or multiple text
+columns in your table.
+
+### Schema Setup
+
+To index columns for full-text search, declare the `@searchable` directive on
+the string fields inside your table schema.
+
+```graphql
+type Movie @table {
+  id: UUID! @default(expr: "uuidV4()")
+  title: String! @searchable # Default language (English)
+  genre: String @searchable
+  description: String @searchable(language: "french") # Custom language
+  rating: Float
+}
+```
+
+- **Stemming Language**: By default, parsing uses English stemming. Configure
+  custom stemming using `@searchable(language: "languagename")`.
+- **Multi-Column Stemming Gotcha**: Ensure all indexed columns use the exact
+  same language when searching over multiple columns in a single query —
+  PostgreSQL requires matching text search configurations for multi-column
+  queries.
+
+______________________________________________________________________
+
+### Full-Text Search Queries
+
+SQL Connect automatically generates a full-text query function for each `@table`
+containing `@searchable` fields in the format: `${pluralType}_search`
+
+```graphql
+# connector/queries.gql
+query SearchMoviesLexical($query: String!) @auth(level: PUBLIC) {
+  movies_search(query: $query, limit: 10) {
+    id
+    title
+    genre
+    description
+  }
+}
+```
+
+______________________________________________________________________
+
+### Tuning Full-Text Queries
+
+Configuring query arguments optimizes match relevance and search styles.
+
+#### 1. Query Formats (`queryFormat` argument)
+
+Configure the search interpretation using the `queryFormat` parameter:
+
+- **`QUERY` (Default)**: Web-style search (e.g., `inception OR matrix`,
+  `-"space-travel"`, quotes for exact matches).
+- **`PLAIN`**: Matches all words in the query string in any lexical order (e.g.,
+  `"brown dog"` matches `"the dog was brown"`).
+- **`PHRASE`**: Matches the exact, contiguous phrase sequence (e.g.,
+  `"brown dog"` matches `"the brown dog"`, but NOT `"dog is brown"`).
+- **`ADVANCED`**: Allows standard, complex PostgreSQL `tsquery` operators (e.g.
+  `inception & (matrix | sci-fi)`).
+
+```graphql
+# connector/queries.gql
+query SearchMoviesExactPhrase($query: String!) @auth(level: PUBLIC) {
+  movies_search(query: $query, queryFormat: PHRASE) {
+    id
+    title
+  }
+}
+```
+
+#### 2. Relevance Thresholding (`relevanceThreshold` and `_metadata.relevance`)
+
+Results default to sorting by descending relevance rank. Select
+`_metadata { relevance }` to inspect match rankings, then set a minimum
+`relevanceThreshold` value to prune loose or irrelevant matches.
+
+```graphql
+# connector/queries.gql
+query SearchMoviesHighRelevance($query: String!, $threshold: Float!) @auth(level: PUBLIC) {
+  movies_search(
+    query: $query,
+    relevanceThreshold: $threshold, # E.g., 0.05
+    limit: 5
+  ) {
+    id
+    title
+    _metadata {
+      relevance
+    }
+  }
+}
+```

package/dist/global-skills/firebase-data-connect/reference/security.md

@@ -0,0 +1,295 @@
+# Security Reference
+
+## Contents
+
+- [@auth Directive](#auth-directive)
+- [Access Levels](#access-levels)
+- [CEL Expressions](#cel-expressions)
+- [@check and @redact](#check-and-redact)
+- [Authorization Patterns](#authorization-patterns)
+- [Anti-Patterns](#anti-patterns)
+
+______________________________________________________________________
+
+## @auth Directive
+
+Every deployable query/mutation must have `@auth`. Without it, operations
+default to `NO_ACCESS`.
+
+```graphql
+query PublicData @auth(level: PUBLIC) { ... }
+query UserData @auth(level: USER) { ... }
+query AdminOnly @auth(expr: "auth.token.admin == true") { ... }
+```
+
+| Argument         | Description                                        |
+| ---------------- | -------------------------------------------------- |
+| `level`          | Preset access level                                |
+| `expr`           | CEL expression (alternative to level)              |
+| `insecureReason` | Suppress deploy warning for PUBLIC/unfiltered USER |
+
+______________________________________________________________________
+
+## Access Levels
+
+| Level                 | Who Can Access                               | CEL Equivalent                                                           |
+| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
+| `PUBLIC`              | Anyone, authenticated or not                 | `true`                                                                   |
+| `USER_ANON`           | Any authenticated user (including anonymous) | `auth.uid != nil`                                                        |
+| `USER`                | Authenticated users (excludes anonymous)     | `auth.uid != nil && auth.token.firebase.sign_in_provider != 'anonymous'` |
+| `USER_EMAIL_VERIFIED` | Users with verified email                    | `auth.uid != nil && auth.token.email_verified`                           |
+| `NO_ACCESS`           | Admin SDK only                               | `false`                                                                  |
+
+> **Important:** Levels like `USER` are starting points. Always add filters or
+> expressions to verify the user can access specific data.
+
+______________________________________________________________________
+
+## CEL Expressions
+
+### Available Bindings
+
+| Binding                 | Description                                |
+| ----------------------- | ------------------------------------------ |
+| `auth.uid`              | Current user's Firebase UID                |
+| `auth.token`            | Auth token claims (see below)              |
+| `vars`                  | Operation variables (e.g., `vars.movieId`) |
+| `request.time`          | Server timestamp                           |
+| `request.operationName` | "query" or "mutation"                      |
+
+### auth.token Fields
+
+| Field                       | Description                                 |
+| --------------------------- | ------------------------------------------- |
+| `email`                     | User's email address                        |
+| `email_verified`            | Boolean: email verified                     |
+| `phone_number`              | User's phone                                |
+| `name`                      | Display name                                |
+| `sub`                       | Firebase UID (same as auth.uid)             |
+| `firebase.sign_in_provider` | `password`, `google.com`, `anonymous`, etc. |
+| `<custom_claim>`            | Custom claims set via Admin SDK             |
+
+### Expression Examples
+
+```graphql
+# Check custom claim
+@auth(expr: "auth.token.role == 'admin'")
+
+# Check verified email domain
+@auth(expr: "auth.token.email_verified && auth.token.email.endsWith('@company.com')")
+
+# Check multiple conditions
+@auth(expr: "auth.uid != nil && (auth.token.role == 'editor' || auth.token.role == 'admin')")
+
+# Check variable
+@auth(expr: "has(vars.status) && vars.status in ['draft', 'published']")
+```
+
+### Using eq_expr in Filters
+
+Compare database fields with auth values:
+
+```graphql
+query MyPosts @auth(level: USER) {
+  posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
+    id title
+  }
+}
+
+mutation UpdateMyPost($id: UUID!, $title: String!) @auth(level: USER) {
+  post_update(
+    first: { where: {
+      id: { eq: $id },
+      authorUid: { eq_expr: "auth.uid" }
+    }},
+    data: { title: $title }
+  )
+}
+```
+
+______________________________________________________________________
+
+## @check and @redact
+
+Use `@check` to validate data and `@redact` to hide results from client:
+
+### @check
+
+Validates a field value; aborts if check fails.
+
+```graphql
+@check(expr: "this != null", message: "Not found")
+@check(expr: "this == 'editor'", message: "Must be editor")
+@check(expr: "this.exists(p, p.role == 'admin')", message: "No admin found")
+```
+
+| Argument   | Description                                  |
+| ---------- | -------------------------------------------- |
+| `expr`     | CEL expression; `this` = current field value |
+| `message`  | Error message if check fails                 |
+| `optional` | If `true`, pass when field not present       |
+
+### @redact
+
+Hides field from response (still evaluated for @check):
+
+```graphql
+query @redact { ... }  # Query result hidden but @check still runs
+```
+
+### Authorization Data Lookup
+
+Check database permissions before allowing mutation:
+
+```graphql
+mutation UpdateMovie($id: UUID!, $title: String!) 
+  @auth(level: USER) 
+  @transaction {
+  # Step 1: Check user has permission
+  query @redact {
+    moviePermission(
+      key: { movieId: $id, userId_expr: "auth.uid" }
+    ) @check(expr: "this != null", message: "No access to movie") {
+      role @check(expr: "this == 'editor'", message: "Must be editor")
+    }
+  }
+  # Step 2: Update if authorized
+  movie_update(id: $id, data: { title: $title })
+}
+```
+
+### Validate Key Exists
+
+```graphql
+mutation MustDeleteMovie($id: UUID!) @auth(level: USER) @transaction {
+  movie_delete(id: $id) 
+    @check(expr: "this != null", message: "Movie not found")
+}
+```
+
+______________________________________________________________________
+
+## Authorization Patterns
+
+### User-Owned Resources
+
+```graphql
+# Create with owner
+mutation CreatePost($content: String!) @auth(level: USER) {
+  post_insert(data: {
+    authorUid_expr: "auth.uid",
+    content: $content
+  })
+}
+
+# Read own data only
+query MyPosts @auth(level: USER) {
+  posts(where: { authorUid: { eq_expr: "auth.uid" }}) {
+    id content
+  }
+}
+
+# Update own data only
+mutation UpdatePost($id: UUID!, $content: String!) @auth(level: USER) {
+  post_update(
+    first: { where: { id: { eq: $id }, authorUid: { eq_expr: "auth.uid" }}},
+    data: { content: $content }
+  )
+}
+
+# Delete own data only
+mutation DeletePost($id: UUID!) @auth(level: USER) {
+  post_delete(
+    first: { where: { id: { eq: $id }, authorUid: { eq_expr: "auth.uid" }}}
+  )
+}
+```
+
+### Role-Based Access
+
+```graphql
+# Admin-only query
+query AllUsers @auth(expr: "auth.token.admin == true") {
+  users { id email name }
+}
+
+# Role from database
+mutation AdminAction($id: UUID!) @auth(level: USER) @transaction {
+  query @redact {
+    user(key: { uid_expr: "auth.uid" }) {
+      role @check(expr: "this == 'admin'", message: "Admin required")
+    }
+  }
+  # ... admin action
+}
+```
+
+### Public Data with Filters
+
+```graphql
+query PublicPosts @auth(level: PUBLIC) {
+  posts(where: {
+    visibility: { eq: "public" },
+    publishedAt: { lt_expr: "request.time" }
+  }) {
+    id title content
+  }
+}
+```
+
+### Tiered Access (Pro Content)
+
+```graphql
+query ProContent @auth(expr: "auth.token.plan == 'pro'") {
+  posts(where: { visibility: { in: ["public", "pro"] }}) {
+    id title content
+  }
+}
+```
+
+______________________________________________________________________
+
+## Anti-Patterns
+
+### ❌ Don't Pass User ID as Variable
+
+```graphql
+# BAD - any user can pass any userId
+query GetUserPosts($userId: String!) @auth(level: USER) {
+  posts(where: { authorUid: { eq: $userId }}) { ... }
+}
+
+# GOOD - use auth.uid
+query GetMyPosts @auth(level: USER) {
+  posts(where: { authorUid: { eq_expr: "auth.uid" }}) { ... }
+}
+```
+
+### ❌ Don't Use USER Without Filters
+
+```graphql
+# BAD - any authenticated user sees all documents
+query AllDocs @auth(level: USER) {
+  documents { id title content }
+}
+
+# GOOD - filter to user's documents
+query MyDocs @auth(level: USER) {
+  documents(where: { ownerId: { eq_expr: "auth.uid" }}) { ... }
+}
+```
+
+### ❌ Don't Trust Unverified Email
+
+```graphql
+# BAD - email not verified
+@auth(expr: "auth.token.email.endsWith('@company.com')")
+
+# GOOD - verify email first
+@auth(expr: "auth.token.email_verified && auth.token.email.endsWith('@company.com')")
+```
+
+### ❌ Don't Use PUBLIC/USER for Prototyping
+
+During development, set operations to `NO_ACCESS` until you implement proper
+authorization. Use emulator and VS Code extension for testing.