Add primary keys for C++ procedural views (#5354)

JasonAtClockwork · web-flow · commit cf73acff9221 · 2026-06-18T22:43:51.000Z
# Description of Changes Adds primary keys to procedural views in C++. This mirrors the work from #5111, #5246, and #5327 adding the feature and the docs changes. # API and ABI breaking changes None # Expected complexity level and risk 3 # Testing - [x] Equivalent tests as were added in #5111 and #5246 for rust, typescript, and C#
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/Module.h b/crates/bindings-cpp/include/spacetimedb/internal/Module.h
@@ -4,6 +4,7 @@
 #include <string>
 #include <vector>
 #include <optional>
+#include <utility>
 #include "../bsatn/types.h"
 #include "../reducer_macros.h"
 #include "../reducer_context.h"
@@ -120,6 +121,7 @@ class Module {
     static void RegisterExplicitTableName(const std::string& source_name, const std::string& canonical_name);
     static void RegisterExplicitFunctionName(const std::string& source_name, const std::string& canonical_name);
     static void RegisterExplicitIndexName(const std::string& source_name, const std::string& canonical_name);
+    static void RegisterViewPrimaryKey(const std::string& view_source_name, std::vector<std::string> columns);
 };
 
 // Helper functions for module description
@@ -178,6 +180,10 @@ class Module {
     static void RegisterExplicitIndexName(const char* source_name, const char* canonical_name) {
         Internal::Module::RegisterExplicitIndexName(source_name, canonical_name);
     }
+
+    static void RegisterViewPrimaryKey(const char* view_source_name, std::vector<std::string> columns) {
+        Internal::Module::RegisterViewPrimaryKey(view_source_name, std::move(columns));
+    }
 };
 
 // Global registration functions for X-Macro support
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawMiscModuleExportV9.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawMiscModuleExportV9.g.h
@@ -13,8 +13,8 @@
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
 #include "RawColumnDefaultValueV9.g.h"
-#include "RawProcedureDefV9.g.h"
 #include "RawViewDefV9.g.h"
+#include "RawProcedureDefV9.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDef.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDef.g.h
@@ -13,8 +13,8 @@
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
 #include "RawModuleDefV8.g.h"
-#include "RawModuleDefV9.g.h"
 #include "RawModuleDefV10.g.h"
+#include "RawModuleDefV9.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV10Section.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV10Section.g.h
@@ -12,21 +12,22 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "RawProcedureDefV10.g.h"
-#include "CaseConversionPolicy.g.h"
-#include "RawLifeCycleReducerDefV10.g.h"
-#include "RawReducerDefV10.g.h"
-#include "RawHttpHandlerDefV10.g.h"
-#include "RawTypeDefV10.g.h"
-#include "ExplicitNames.g.h"
+#include "RawViewPrimaryKeyDefV10.g.h"
+#include "RawTableDefV10.g.h"
 #include "RawViewDefV10.g.h"
 #include "RawScheduleDefV10.g.h"
-#include "Typespace.g.h"
-#include "RawTableDefV10.g.h"
+#include "CaseConversionPolicy.g.h"
 #include "RawRowLevelSecurityDefV9.g.h"
 #include "RawHttpRouteDefV10.g.h"
+#include "RawReducerDefV10.g.h"
+#include "Typespace.g.h"
+#include "RawLifeCycleReducerDefV10.g.h"
+#include "ExplicitNames.g.h"
+#include "RawHttpHandlerDefV10.g.h"
+#include "RawTypeDefV10.g.h"
+#include "RawProcedureDefV10.g.h"
 
 namespace SpacetimeDB::Internal {
 
-SPACETIMEDB_INTERNAL_TAGGED_ENUM(RawModuleDefV10Section, SpacetimeDB::Internal::Typespace, std::vector<SpacetimeDB::Internal::RawTypeDefV10>, std::vector<SpacetimeDB::Internal::RawTableDefV10>, std::vector<SpacetimeDB::Internal::RawReducerDefV10>, std::vector<SpacetimeDB::Internal::RawProcedureDefV10>, std::vector<SpacetimeDB::Internal::RawViewDefV10>, std::vector<SpacetimeDB::Internal::RawScheduleDefV10>, std::vector<SpacetimeDB::Internal::RawLifeCycleReducerDefV10>, std::vector<SpacetimeDB::Internal::RawRowLevelSecurityDefV9>, SpacetimeDB::Internal::CaseConversionPolicy, SpacetimeDB::Internal::ExplicitNames, std::vector<SpacetimeDB::Internal::RawHttpHandlerDefV10>, std::vector<SpacetimeDB::Internal::RawHttpRouteDefV10>)
+SPACETIMEDB_INTERNAL_TAGGED_ENUM(RawModuleDefV10Section, SpacetimeDB::Internal::Typespace, std::vector<SpacetimeDB::Internal::RawTypeDefV10>, std::vector<SpacetimeDB::Internal::RawTableDefV10>, std::vector<SpacetimeDB::Internal::RawReducerDefV10>, std::vector<SpacetimeDB::Internal::RawProcedureDefV10>, std::vector<SpacetimeDB::Internal::RawViewDefV10>, std::vector<SpacetimeDB::Internal::RawScheduleDefV10>, std::vector<SpacetimeDB::Internal::RawLifeCycleReducerDefV10>, std::vector<SpacetimeDB::Internal::RawRowLevelSecurityDefV9>, SpacetimeDB::Internal::CaseConversionPolicy, SpacetimeDB::Internal::ExplicitNames, std::vector<SpacetimeDB::Internal::RawHttpHandlerDefV10>, std::vector<SpacetimeDB::Internal::RawHttpRouteDefV10>, std::vector<SpacetimeDB::Internal::RawViewPrimaryKeyDefV10>)
 } // namespace SpacetimeDB::Internal
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV8.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV8.g.h
@@ -13,9 +13,9 @@
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
 #include "MiscModuleExport.g.h"
-#include "ReducerDef.g.h"
-#include "TableDesc.g.h"
 #include "Typespace.g.h"
+#include "TableDesc.g.h"
+#include "ReducerDef.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV9.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawModuleDefV9.g.h
@@ -13,11 +13,11 @@
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
 #include "RawTableDefV9.g.h"
-#include "RawRowLevelSecurityDefV9.g.h"
-#include "Typespace.g.h"
 #include "RawReducerDefV9.g.h"
 #include "RawTypeDefV9.g.h"
+#include "Typespace.g.h"
 #include "RawMiscModuleExportV9.g.h"
+#include "RawRowLevelSecurityDefV9.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawProcedureDefV10.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawProcedureDefV10.g.h
@@ -12,9 +12,9 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "AlgebraicType.g.h"
 #include "FunctionVisibility.g.h"
 #include "ProductType.g.h"
+#include "AlgebraicType.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawProcedureDefV9.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawProcedureDefV9.g.h
@@ -12,8 +12,8 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "ProductType.g.h"
 #include "AlgebraicType.g.h"
+#include "ProductType.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawReducerDefV10.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawReducerDefV10.g.h
@@ -12,8 +12,8 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "ProductType.g.h"
 #include "FunctionVisibility.g.h"
+#include "ProductType.g.h"
 #include "AlgebraicType.g.h"
 
 namespace SpacetimeDB::Internal {
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawReducerDefV9.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawReducerDefV9.g.h
@@ -12,8 +12,8 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "Lifecycle.g.h"
 #include "ProductType.g.h"
+#include "Lifecycle.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawTableDefV10.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawTableDefV10.g.h
@@ -12,11 +12,11 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
+#include "TableType.g.h"
 #include "TableAccess.g.h"
-#include "RawSequenceDefV10.g.h"
-#include "RawConstraintDefV10.g.h"
 #include "RawIndexDefV10.g.h"
-#include "TableType.g.h"
+#include "RawConstraintDefV10.g.h"
+#include "RawSequenceDefV10.g.h"
 #include "RawColumnDefaultValueV10.g.h"
 
 namespace SpacetimeDB::Internal {
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawTableDefV8.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawTableDefV8.g.h
@@ -12,8 +12,8 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "RawIndexDefV8.g.h"
 #include "RawSequenceDefV8.g.h"
+#include "RawIndexDefV8.g.h"
 #include "RawConstraintDefV8.g.h"
 #include "RawColumnDefV8.g.h"
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawTableDefV9.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawTableDefV9.g.h
@@ -12,12 +12,12 @@
 #include <memory>
 #include "../autogen_base.h"
 #include "spacetimedb/bsatn/bsatn.h"
-#include "TableType.g.h"
+#include "RawConstraintDefV9.g.h"
 #include "RawSequenceDefV9.g.h"
-#include "TableAccess.g.h"
 #include "RawIndexDefV9.g.h"
-#include "RawConstraintDefV9.g.h"
 #include "RawScheduleDefV9.g.h"
+#include "TableAccess.g.h"
+#include "TableType.g.h"
 
 namespace SpacetimeDB::Internal {
 
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawViewPrimaryKeyDefV10.g.h b/crates/bindings-cpp/include/spacetimedb/internal/autogen/RawViewPrimaryKeyDefV10.g.h
@@ -0,0 +1,28 @@
+// THIS FILE IS AUTOMATICALLY GENERATED BY SPACETIMEDB. EDITS TO THIS FILE
+// WILL NOT BE SAVED. MODIFY TABLES IN YOUR MODULE SOURCE CODE INSTEAD.
+
+// This was generated using spacetimedb codegen.
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+#include <optional>
+#include <memory>
+#include "../autogen_base.h"
+#include "spacetimedb/bsatn/bsatn.h"
+
+namespace SpacetimeDB::Internal {
+
+SPACETIMEDB_INTERNAL_PRODUCT_TYPE(RawViewPrimaryKeyDefV10) {
+    std::string view_source_name;
+    std::vector<std::string> columns;
+
+    void bsatn_serialize(::SpacetimeDB::bsatn::Writer& writer) const {
+        ::SpacetimeDB::bsatn::serialize(writer, view_source_name);
+        ::SpacetimeDB::bsatn::serialize(writer, columns);
+    }
+    SPACETIMEDB_PRODUCT_TYPE_EQUALITY(view_source_name, columns)
+};
+} // namespace SpacetimeDB::Internal
diff --git a/crates/bindings-cpp/include/spacetimedb/internal/v10_builder.h b/crates/bindings-cpp/include/spacetimedb/internal/v10_builder.h
@@ -26,6 +26,7 @@
 #include "autogen/RawReducerDefV10.g.h"
 #include "autogen/RawProcedureDefV10.g.h"
 #include "autogen/RawViewDefV10.g.h"
+#include "autogen/RawViewPrimaryKeyDefV10.g.h"
 #include "autogen/RawScheduleDefV10.g.h"
 #include "autogen/RawLifeCycleReducerDefV10.g.h"
 #include "autogen/RawHttpHandlerDefV10.g.h"
@@ -632,6 +633,10 @@ class V10Builder {
         row_level_security_.push_back(RawRowLevelSecurityDefV9{sql_query});
     }
 
+    void RegisterViewPrimaryKey(const std::string& view_source_name, std::vector<std::string> columns) {
+        view_primary_keys_.push_back(RawViewPrimaryKeyDefV10{view_source_name, std::move(columns)});
+    }
+
     void SetTableIsEventFlag(const std::string& table_name, bool is_event);
     bool GetTableIsEventFlag(const std::string& table_name) const;
 
@@ -686,6 +691,7 @@ class V10Builder {
     std::vector<RawReducerDefV10> reducers_;
     std::vector<RawProcedureDefV10> procedures_;
     std::vector<RawViewDefV10> views_;
+    std::vector<RawViewPrimaryKeyDefV10> view_primary_keys_;
     std::vector<RawHttpHandlerDefV10> http_handlers_;
     std::vector<RawHttpRouteDefV10> http_routes_;
     std::vector<RawScheduleDefV10> schedules_;
@@ -704,4 +710,3 @@ V10Builder& getV10Builder();
 } // namespace SpacetimeDB
 
 #endif // SPACETIMEDB_V10_BUILDER_H
-
diff --git a/crates/bindings-cpp/include/spacetimedb/view_macros.h b/crates/bindings-cpp/include/spacetimedb/view_macros.h
@@ -4,11 +4,13 @@
 #include "spacetimedb/query_builder.h"
 #include "spacetimedb/internal/Module.h"
 #include "spacetimedb/internal/v10_builder.h"
+#include "spacetimedb/table_with_constraints.h"
 #include "spacetimedb/macros.h"  // For parseParameterNames
 #include "spacetimedb/error_handling.h"
 #include <string>
 #include <vector>
 #include <type_traits>
+#include <utility>
 
 namespace SpacetimeDB {
 namespace Internal {
@@ -151,3 +153,19 @@ struct is_valid_view_return_type
         SpacetimeDB::Module::RegisterExplicitFunctionName(#view_name, canonical_name); \
     } \
     return_type view_name(ctx_param)
+
+#define VIEW_PrimaryKey(view_name, field_name) \
+    static_assert([]() constexpr { \
+        using RowType = typename std::remove_cv_t<decltype(view_name##_view)>::type; \
+        using FieldType = decltype(std::declval<RowType>().field_name); \
+        static_assert(::SpacetimeDB::FilterableValue<FieldType>, \
+            "View primary key field '" #field_name "' must have a filterable type."); \
+        return true; \
+    }(), "View primary key validation for " #view_name "." #field_name); \
+    inline std::true_type indexed_member_lookup(::SpacetimeDB::query_builder::member_tag< \
+        typename std::remove_cv_t<decltype(view_name##_view)>::type, \
+        &std::remove_cv_t<decltype(view_name##_view)>::type::field_name>); \
+    extern "C" __attribute__((export_name("__preinit__41_view_primary_key_" #view_name "_" #field_name "_line_" SPACETIMEDB_STRINGIFY(__LINE__)))) \
+    void SPACETIMEDB_PASTE(__preinit__41_view_primary_key_, SPACETIMEDB_PASTE(view_name, SPACETIMEDB_PASTE(_, SPACETIMEDB_PASTE(field_name, SPACETIMEDB_PASTE(_line_, __LINE__)))))() { \
+        ::SpacetimeDB::Module::RegisterViewPrimaryKey(#view_name, std::vector<std::string>{#field_name}); \
+    }
diff --git a/crates/bindings-cpp/src/internal/Module.cpp b/crates/bindings-cpp/src/internal/Module.cpp
@@ -691,6 +691,10 @@ void Module::RegisterExplicitFunctionName(const std::string& source_name, const
 void Module::RegisterExplicitIndexName(const std::string& source_name, const std::string& canonical_name) {
     getV10Builder().RegisterExplicitIndexName(source_name, canonical_name);
 }
+
+void Module::RegisterViewPrimaryKey(const std::string& view_source_name, std::vector<std::string> columns) {
+    getV10Builder().RegisterViewPrimaryKey(view_source_name, std::move(columns));
+}
 }
 }
 
diff --git a/crates/bindings-cpp/src/internal/v10_builder.cpp b/crates/bindings-cpp/src/internal/v10_builder.cpp
@@ -38,6 +38,7 @@ void V10Builder::Clear() {
     reducers_.clear();
     procedures_.clear();
     views_.clear();
+    view_primary_keys_.clear();
     http_handlers_.clear();
     http_routes_.clear();
     schedules_.clear();
@@ -303,6 +304,11 @@ RawModuleDefV10 V10Builder::BuildModuleDef() const {
         section_http_routes.set<12>(http_routes_);
         v10_module.sections.push_back(std::move(section_http_routes));
     }
+    if (!view_primary_keys_.empty()) {
+        RawModuleDefV10Section section_view_primary_keys;
+        section_view_primary_keys.set<13>(view_primary_keys_);
+        v10_module.sections.push_back(std::move(section_view_primary_keys));
+    }
     if (!row_level_security_.empty()) {
         RawModuleDefV10Section section_rls;
         section_rls.set<8>(row_level_security_);
diff --git a/docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md b/docs/docs/00200-core-concepts/00100-databases/00500-cheat-sheet.md
@@ -739,6 +739,12 @@ SPACETIMEDB_VIEW(std::vector<Player>, top_players, Public, ViewContext ctx) {
     return ctx.db[player_score].filter(range_from(int32_t(1000))).collect();
 }
 
+// Procedural view with update callbacks.
+SPACETIMEDB_VIEW(std::vector<Player>, top_players_with_updates, Public, ViewContext ctx) {
+    return ctx.db[player_score].filter(range_from(int32_t(1000))).collect();
+}
+VIEW_PrimaryKey(top_players_with_updates, id)
+
 // Perform a generic filter using the query builder.
 // Equivalent to `SELECT * FROM player WHERE score < 1000`.
 SPACETIMEDB_VIEW(Query<Player>, bottom_players, Public, ViewContext ctx) {
diff --git a/docs/docs/00200-core-concepts/00200-functions/00500-views.md b/docs/docs/00200-core-concepts/00200-functions/00500-views.md
@@ -1436,7 +1436,7 @@ Generated client bindings treat these views like primary-key tables for client-c
 In particular, update callbacks (`on_update` / `OnUpdate` / `onUpdate`) are generated for these view handles.
 Views without a known primary key fall back to insert/delete-only behavior.
 
-For procedural views, primary keys are declared in the view definition for Rust and C#.
+For procedural views, primary keys are declared in the view definition for Rust and C#, and with a post-view declaration macro in C++.
 In TypeScript, you mark one of the columns in the returned row type with `.primaryKey()`.
 View primary keys refer to source/accessor names, not case-converted or canonical database column names.
 The examples below use a `Player` row with a primary-key `id` / `Id` column and an indexed `owner` / `Owner` column.
@@ -1487,6 +1487,16 @@ fn my_players(ctx: &ViewContext) -> Vec<Player> {
 }
 ```
 
+</TabItem>
+<TabItem value="cpp" label="C++">
+
+```cpp
+SPACETIMEDB_VIEW(std::vector<Player>, my_players, Public, ViewContext ctx) {
+    return ctx.db[player_owner].filter(ctx.sender()).collect();
+}
+VIEW_PrimaryKey(my_players, id)
+```
+
 </TabItem>
 </Tabs>
 
diff --git a/modules/sdk-test-procedural-view-pk-cpp/.gitignore b/modules/sdk-test-procedural-view-pk-cpp/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/modules/sdk-test-procedural-view-pk-cpp/CMakeLists.txt b/modules/sdk-test-procedural-view-pk-cpp/CMakeLists.txt
diff --git a/modules/sdk-test-procedural-view-pk-cpp/README.md b/modules/sdk-test-procedural-view-pk-cpp/README.md
diff --git a/modules/sdk-test-procedural-view-pk-cpp/src/lib.cpp b/modules/sdk-test-procedural-view-pk-cpp/src/lib.cpp
diff --git a/sdks/rust/tests/procedural-view-pk-client/src/module_bindings/mod.rs b/sdks/rust/tests/procedural-view-pk-client/src/module_bindings/mod.rs
diff --git a/sdks/rust/tests/test.rs b/sdks/rust/tests/test.rs
