Update sql table column descriptions

This commit updates the sql table column descriptions wrt feedback
from restatedev/documentation#422.

crates/storage-query-datafusion/src/idempotency/schema.rs

@@ -18,10 +18,10 @@ define_table!(sys_idempotency(
     /// Internal column that is used for partitioning the services invocations. Can be ignored.
     partition_key: DataType::UInt64,
 
-    /// The name for the invoked service.
+    /// The name of the invoked service.
     service_name: DataType::LargeUtf8,
 
-    /// The key of the Virtual Object or of the Workflow. Null for regular services.
+    /// The key of the virtual object or the workflow ID. Null for regular services.
     service_key: DataType::LargeUtf8,
 
     /// The invoked handler.

crates/storage-query-datafusion/src/inbox/schema.rs

@@ -18,7 +18,7 @@ define_table!(sys_inbox(
     /// Internal column that is used for partitioning the services invocations. Can be ignored.
     partition_key: DataType::UInt64,
 
-    /// The name for the invoked virtual object/workflow.
+    /// The name of the invoked virtual object/workflow.
     service_name: DataType::LargeUtf8,
 
     /// The key of the virtual object/workflow.

crates/storage-query-datafusion/src/invocation_state/schema.rs

@@ -24,8 +24,9 @@ define_table!(sys_invocation_state(
     /// If true, the invocation is currently in-flight
     in_flight: DataType::Boolean,
 
-    /// The number of attempts since the last successful attempt of this invocation.
-    /// Increments on start, so 2 or more means a failure occurred.
+    /// The number of invocation attempts since the current leader started executing it. Increments
+    /// on start, so a value greater than 1 means a failure occurred. Note: the value is not a
+    /// global attempt counter across invocation suspensions and leadership changes.
     retry_count: DataType::UInt64,
 
     /// Timestamp indicating the start of the most recent attempt of this invocation.
@@ -35,8 +36,8 @@ define_table!(sys_invocation_state(
     // guaranteed to be set unlike in `sys_status` table which require that the
     // deployment to be committed before it is set.
 
-    /// The opaque service deployment ID that was used in the most recent attempt of this
-    /// invocation; this will be set before a journal entry is stored, but can change later.
+    /// The ID of the service deployment that executed the most recent attempt of this invocation;
+    /// this is set before a journal entry is stored, but can change later.
     last_attempt_deployment_id: DataType::LargeUtf8,
 
     /// Server/SDK version, e.g. `restate-sdk-java/1.0.1`

crates/storage-query-datafusion/src/invocation_status/schema.rs

@@ -25,14 +25,14 @@ define_table!(sys_invocation_status(
     status: DataType::LargeUtf8,
 
     /// Invocation Target. Format for plain services: `ServiceName/HandlerName`, e.g.
-    /// `Greeter/greet`. Format for Virtual Objects/Workflows: `VirtualObjectName/Key/HandlerName`,
+    /// `Greeter/greet`. Format for virtual objects/workflows: `VirtualObjectName/Key/HandlerName`,
     /// e.g. `Greeter/Francesco/greet`.
     target: DataType::LargeUtf8,
 
-    /// The name for the invoked service.
+    /// The name of the invoked service.
     target_service_name: DataType::LargeUtf8,
 
-    /// The key of the Virtual Object or of the Workflow. Null for regular services.
+    /// The key of the virtual object or the workflow ID. Null for regular services.
     target_service_key: DataType::LargeUtf8,
 
     /// The invoked handler.
@@ -56,8 +56,9 @@ define_table!(sys_invocation_status(
     /// `null` if invoked externally.
     invoked_by_target: DataType::LargeUtf8,
 
-    /// The opaque service deployment ID that has been committed for this invocation; this is set
-    /// after the first journal entry is stored for this invocation.
+    /// The ID of the service deployment that started processing this invocation, and will continue
+    /// to do so (e.g. for retries). This gets set after the first journal entry has been stored for
+    /// this invocation.
     pinned_deployment_id: DataType::LargeUtf8,
 
     /// The ID of the trace that is assigned to this invocation. Only relevant when tracing is
@@ -70,7 +71,7 @@ define_table!(sys_invocation_status(
     /// Timestamp indicating the start of this invocation.
     created_at: DataType::Date64,
 
-    /// Timestamp indicating the last state transition. For example, last time the status changed
-    /// from `invoked` to `suspended`.
+    /// Timestamp indicating the last invocation status transition. For example, last time the
+    /// status changed from `invoked` to `suspended`.
     modified_at: DataType::Date64,
 ));

crates/storage-query-datafusion/src/journal/schema.rs

@@ -39,7 +39,8 @@ define_table!(sys_journal(
 
     /// If this entry represents an outbound invocation, indicates the invocation Target. Format
     /// for plain services: `ServiceName/HandlerName`, e.g. `Greeter/greet`. Format for
-    /// Virtual Objects/Workflows: `VirtualObjectName/Key/HandlerName`, e.g. `Greeter/Francesco/greet`.
+    /// virtual objects/workflows: `VirtualObjectName/Key/HandlerName`, e.g.
+    /// `Greeter/Francesco/greet`.
     invoked_target: DataType::LargeUtf8,
 
     /// If this entry represents a sleep, indicates wakeup time.

crates/storage-query-datafusion/src/keyed_service_status/schema.rs

@@ -18,7 +18,7 @@ define_table!(sys_keyed_service_status(
     /// Internal column that is used for partitioning the services invocations. Can be ignored.
     partition_key: DataType::UInt64,
 
-    /// The name for the invoked virtual object/workflow.
+    /// The name of the invoked virtual object/workflow.
     service_name: DataType::LargeUtf8,
 
     /// The key of the virtual object/workflow.

crates/storage-query-datafusion/src/promise/schema.rs

@@ -18,10 +18,10 @@ define_table!(sys_promise(
     /// Internal column that is used for partitioning the services invocations. Can be ignored.
     partition_key: DataType::UInt64,
 
-    /// The name for the workflow.
+    /// The name of the workflow service.
     service_name: DataType::LargeUtf8,
 
-    /// The key of the virtual workflow.
+    /// The workflow ID.
     service_key: DataType::LargeUtf8,
 
     /// The promise key.

crates/storage-query-datafusion/src/state/schema.rs

@@ -28,7 +28,8 @@ define_table!(state(
     key: DataType::LargeUtf8,
 
     /// Only contains meaningful values when a service stores state as `utf8`. This is the case for
-    /// TypeScript services since the TypeScript SDK serializes values as JSON.
+    /// services that serialize state using JSON (default for Typescript SDK, Java/Kotlin SDK if
+    /// using JsonSerdes).
     value_utf8: DataType::LargeUtf8,
 
     /// A binary, uninterpreted representation of the value. You can use the more specific column