tags

TagsService

A flexible tagging service supporting pure labels, metadata tags (name-value pairs), and multi-user tagging for any entity.

Features

• Pure Tags: Simple labels like "Favorites", "Rock", "To Read"
• Metadata Tags: Name-value pairs like venue="Wembley Stadium", year="2024"
• Multi-User Tagging: Multiple users can apply the same tag to an entity
• Tag Ownership: Tags belong to users/organizations with privacy scopes
• Denormalized Counts: Fast access via pre-aggregated usage counts
• Inline Tag Creation: Create tags on-the-fly when tagging entities
• Backend Agnostic: Works with GORM (PostgreSQL/MySQL/SQLite) and Google Cloud Datastore

Architecture

TagsService Interface (Public API)
    |
BaseTagsService (Shared logic + caching)
    |                    |
gRPC Server          Connect RPC Adapter
(embedded)           (ConnectTagsServer)
    |
TagsStorageProvider Interface (Storage abstraction)
    |
Concrete Backends
    +-- GORMTagsService (SQL databases)
    +-- DatastoreTagsService (Google Cloud)

gRPC and Connect Support

The service is directly registrable as a gRPC server and includes a Connect RPC adapter:

import (
    "github.com/panyam/goapplib/content/services/tags"
    "github.com/panyam/goapplib/content/services/tags/backends"
    tagsv1 "github.com/panyam/goapplib/content/gen/go/tags/v1"
    "github.com/panyam/goapplib/content/gen/go/tags/v1/tagsv1connect"
)

// Create service
service := backends.NewGORMTagsService(db)

// Register as gRPC server
grpcServer := grpc.NewServer()
tagsv1.RegisterTagsServiceServer(grpcServer, service)

// Register as Connect handler (HTTP/2 + JSON)
mux := http.NewServeMux()
path, handler := tagsv1connect.NewTagsServiceHandler(tags.NewConnectTagsServer(service))
mux.Handle(path, handler)

Quick Start

GORM Backend (PostgreSQL/MySQL/SQLite)

import (
    "github.com/panyam/goapplib/content/services/tags/backends"
    "gorm.io/gorm"
)

// Create service
db, _ := gorm.Open(sqlite.Open("test.db"), &gorm.Config{})
service := backends.NewGORMTagsService(db)

// Auto-migrate tables
service.AutoMigrate()

// Create a tag
createResp, err := service.CreateTag(ctx, &v1.CreateTagRequest{
    Value:     "Rock",
    OwnerId:   "user-123",
    Scope:     v1.TagScope_TAG_SCOPE_PRIVATE,
})

// Tag an entity
tagResp, err := service.TagEntity(ctx, &v1.TagEntityRequest{
    EntityId:   "song-456",
    TagId:      createResp.Tag.Id,
    TaggedBy:   "user-123",
})

Datastore Backend (Google Cloud)

import (
    "cloud.google.com/go/datastore"
    "github.com/panyam/goapplib/content/services/tags/backends"
)

client, _ := datastore.NewClient(ctx, "my-project")
service := backends.NewDatastoreTagsService(client, "my-namespace")

// Create a tag with inline tagging
tagResp, err := service.TagEntity(ctx, &v1.TagEntityRequest{
    EntityId:   "book-123",
    Value:      "To Read",
    OwnerId:    "user-456",
    TaggedBy:   "user-456",
})

API Reference

Tag Management

Entity Tagging

Advanced Operations

Tag Types

Pure Tags (Labels)

Simple labels without a name component:

// Creates a tag with value="Favorites", name=""
service.CreateTag(ctx, &v1.CreateTagRequest{
    Value:     "Favorites",
    OwnerId:   "user-123",
})

Metadata Tags (Name-Value Pairs)

Structured tags with both name and value:

// Creates a tag with name="venue", value="Wembley Stadium"
service.CreateTag(ctx, &v1.CreateTagRequest{
    Name:      "venue",
    Value:     "Wembley Stadium",
    OwnerId:   "user-123",
})

Tag Scopes

Multi-User Tagging

Multiple users can apply the same tag to the same entity. Each application is tracked separately via the tagged_by field:

// User 1 tags a book
service.TagEntity(ctx, &v1.TagEntityRequest{
    EntityId:   "book-123",
    TagId:      tagID,
    TaggedBy:   "user-1",
})

// User 2 also tags the same book with the same tag
service.TagEntity(ctx, &v1.TagEntityRequest{
    EntityId:   "book-123",
    TagId:      tagID,
    TaggedBy:   "user-2",
})

// User 1 removes their tag (User 2's tag remains)
service.UntagEntity(ctx, &v1.UntagEntityRequest{
    EntityId:   "book-123",
    TagId:      tagID,
    TaggedBy:   "user-1",
})

Data Models

Tag

message Tag {
  string id = 1;
  string owner_id = 3;
  string name = 4;             // For metadata tags (optional)
  string normalized_name = 5;
  string value = 6;            // The tag label
  string normalized_value = 7; // Lowercase for deduplication
  TagScope scope = 8;
  TagState state = 9;
  int64 usage_count = 10;      // Denormalized count
  // timestamps...
}

EntityTag

message EntityTag {
  string id = 1;
  string tag_id = 2;
  string entity_type = 3;    // "post", "song", "book"
  string entity_id = 4;
  string tagged_by = 5;      // User who applied this tag
  EntityTagVisibility visibility = 6;
  // timestamps...
}

Database Schema

GORM Tables

• tags - Tag definitions with composite unique index on (owner_id, normalized_name, normalized_value)
• entity_tags - Tag applications with composite unique index on (tag_id, entity_type, entity_id, tagged_by)

Datastore Kinds

• Tag - Tag definition entities
• EntityTag - Tag application entities with composite key

Datastore Indexes

The Datastore backend requires composite indexes for complex queries. Enable validation at construction:

import dsidx "github.com/panyam/goapplib/datastore"

// Validate indexes during construction (recommended for production)
service, err := backends.NewDatastoreTagsService(client, namespace,
    dsidx.WithValidation(ctx))
if err != nil {
    // Error includes missing indexes + gcloud command to fix
    // Also writes tags_index.yaml automatically
    log.Fatal(err)
}

// Or skip validation (e.g., for emulator)
service, err := backends.NewDatastoreTagsService(client, namespace)

To deploy indexes manually:

gcloud datastore indexes create tags_index.yaml

Integration Testing

Running Tests with SQLite (Default)

cd content
go test ./tests/gorm/... -run TestTagsService

Running Tests with PostgreSQL

# Start PostgreSQL
make updb

# Run tests
make testpg

# Stop PostgreSQL
make downdb

Running Tests with Datastore Emulator

# Start emulator
make upds

# Run tests
make testds

# Stop emulator
make downds

Running Tests with Real Datastore

make testrealDS DS_REAL_PROJECT=my-project DS_REAL_CREDENTIALS=~/creds.json

Best Practices

1. Use Normalized Values: Tags are deduplicated using normalized (lowercase) values. "Rock" and "ROCK" are the same tag.

2. Choose Appropriate Scope: Start with private tags and promote to shared/public as needed.

3. Use Inline Creation: When tagging entities, use the inline creation feature to create tags on-the-fly:

   service.TagEntity(ctx, &v1.TagEntityRequest{
       EntityId:   "book-123",
       Value:      "To Read",  // Creates tag if not exists
       OwnerId:    "user-456",
       TaggedBy:   "user-456",
   })
   

4. Leverage Metadata Tags: For structured data like locations, dates, or custom attributes, use name-value pairs instead of encoding data in plain tag values.

Design Notes

The Tag model uses name instead of key for the metadata identifier field. This avoids a naming collision in the Datastore generator where proto field key becomes Go field Key, conflicting with the auto-generated Key *datastore.Key field.

See Also

• content/protos/tags/v1/ - Proto definitions
• ../SUMMARY.md - Content services overview