sqlite_graphrag/commands/
rename_entity.rs

1//! Handler for the `rename-entity` CLI subcommand.
2//!
3//! Renames an entity preserving all relationships and memory bindings.
4//! Only the `name` column in `entities` and the corresponding `vec_entities`
5//! row need updating because relationships use integer FK `entity_id`.
6
7use crate::entity_type::EntityType;
8use crate::errors::AppError;
9use crate::i18n::errors_msg;
10use crate::output::{self, OutputFormat};
11use crate::paths::AppPaths;
12use crate::storage::connection::open_rw;
13use crate::storage::entities;
14use rusqlite::params;
15use serde::Serialize;
16
17#[derive(clap::Args)]
18#[command(after_long_help = "EXAMPLES:\n  \
19    # Rename an entity\n  \
20    sqlite-graphrag rename-entity --name old-name --new-name new-name\n\n  \
21    # Rename with namespace\n  \
22    sqlite-graphrag rename-entity --name auth --new-name authentication --namespace my-project")]
23pub struct RenameEntityArgs {
24    /// Current entity name to rename.
25    #[arg(long, value_name = "NAME")]
26    pub name: String,
27    /// New name for the entity.
28    #[arg(long, value_name = "NEW_NAME")]
29    pub new_name: String,
30    #[arg(long)]
31    pub namespace: Option<String>,
32    #[arg(long, value_enum, default_value = "json")]
33    pub format: OutputFormat,
34    #[arg(long, hide = true, help = "No-op; JSON is always emitted on stdout")]
35    pub json: bool,
36    #[arg(long, env = "SQLITE_GRAPHRAG_DB_PATH")]
37    pub db: Option<String>,
38}
39
40#[derive(Serialize)]
41struct RenameEntityResponse {
42    action: String,
43    old_name: String,
44    new_name: String,
45    entity_id: i64,
46    namespace: String,
47    elapsed_ms: u64,
48}
49
50pub fn run(
51    args: RenameEntityArgs,
52    llm_backend: crate::cli::LlmBackendChoice,
53    embedding_backend: crate::cli::EmbeddingBackendChoice,
54) -> Result<(), AppError> {
55    let start = std::time::Instant::now();
56    let namespace = crate::namespace::resolve_namespace(args.namespace.as_deref())?;
57    let paths = AppPaths::resolve(args.db.as_deref())?;
58
59    crate::storage::connection::ensure_db_ready(&paths)?;
60
61    let mut conn = open_rw(&paths.db)?;
62
63    // Verify source entity exists and fetch its id and type.
64    // Normalize the lookup name to match the normalized stored names.
65    let lookup_name = crate::parsers::normalize_entity_name(&args.name);
66    let row: Option<(i64, EntityType)> = {
67        let mut stmt = conn
68            .prepare_cached("SELECT id, type FROM entities WHERE namespace = ?1 AND name = ?2")?;
69        match stmt.query_row(params![namespace, lookup_name], |r| {
70            Ok((r.get::<_, i64>(0)?, r.get::<_, EntityType>(1)?))
71        }) {
72            Ok(row) => Some(row),
73            Err(rusqlite::Error::QueryReturnedNoRows) => None,
74            Err(e) => return Err(AppError::Database(e)),
75        }
76    };
77    let (entity_id, entity_type) = row
78        .ok_or_else(|| AppError::NotFound(errors_msg::entity_not_found(&args.name, &namespace)))?;
79
80    // Validate the raw new name first (catches short ALL_CAPS NER noise),
81    // then normalize it for storage to preserve the normalized-name invariant.
82    entities::validate_entity_name(&args.new_name)?;
83    let new_name = crate::parsers::normalize_entity_name(&args.new_name);
84
85    if lookup_name == new_name {
86        return Err(AppError::Validation(
87            "source and target entity names are identical".to_string(),
88        ));
89    }
90
91    // Ensure new name is not already taken in this namespace.
92    if entities::find_entity_id(&conn, &namespace, &new_name)?.is_some() {
93        return Err(AppError::Validation(format!(
94            "entity with name '{new_name}' already exists in namespace '{namespace}'"
95        )));
96    }
97
98    let skip_embed = crate::embedder::should_skip_embedding_on_failure();
99    let embedding: Option<Vec<f32>> = match crate::embedder::embed_passage_with_embedding_choice(
100        &paths.models,
101        &new_name,
102        embedding_backend,
103        llm_backend,
104    ) {
105        Ok((emb, _backend)) => Some(emb),
106        Err(AppError::Validation(msg)) => return Err(AppError::Validation(msg)),
107        Err(e) if skip_embed => {
108            tracing::warn!(error = %e, "rename-entity: embedding failed; --skip-embedding-on-failure active, persisting without embedding");
109            None
110        }
111        Err(e) => return Err(e),
112    };
113
114    let tx = conn.transaction_with_behavior(rusqlite::TransactionBehavior::Immediate)?;
115    tx.execute(
116        "UPDATE entities SET name = ?1, updated_at = unixepoch() WHERE id = ?2",
117        params![new_name, entity_id],
118    )?;
119    // v1.0.76: BLOB-backed entity_embeddings table (PK = entity_id).
120    // G43: reuse the canonical writer instead of a duplicated INSERT that
121    // hardcoded dim=384 and a removed local model name; `upsert_entity_vec`
122    // records the real vector length and the CLI version as `model`.
123    if let Some(ref emb) = embedding {
124        entities::upsert_entity_vec(&tx, entity_id, &namespace, entity_type, emb, &new_name)?;
125    }
126    tx.commit()?;
127
128    conn.execute_batch("PRAGMA wal_checkpoint(TRUNCATE);")?;
129
130    let response = RenameEntityResponse {
131        action: "renamed".to_string(),
132        old_name: args.name,
133        new_name,
134        entity_id,
135        namespace: namespace.clone(),
136        elapsed_ms: start.elapsed().as_millis() as u64,
137    };
138
139    match args.format {
140        OutputFormat::Json => output::emit_json(&response)?,
141        OutputFormat::Text | OutputFormat::Markdown => {
142            output::emit_text(&format!(
143                "renamed entity: '{}' → '{}' [{}]",
144                response.old_name, response.new_name, response.namespace
145            ));
146        }
147    }
148
149    Ok(())
150}
151
152#[cfg(test)]
153mod tests {
154    use super::*;
155
156    #[test]
157    fn rename_entity_response_serializes_all_fields() {
158        let resp = RenameEntityResponse {
159            action: "renamed".to_string(),
160            old_name: "auth".to_string(),
161            new_name: "authentication".to_string(),
162            entity_id: 42,
163            namespace: "global".to_string(),
164            elapsed_ms: 7,
165        };
166        let json = serde_json::to_value(&resp).expect("serialization failed");
167        assert_eq!(json["action"], "renamed");
168        assert_eq!(json["old_name"], "auth");
169        assert_eq!(json["new_name"], "authentication");
170        assert_eq!(json["entity_id"], 42);
171        assert_eq!(json["namespace"], "global");
172        assert!(json["elapsed_ms"].is_number());
173    }
174
175    #[test]
176    fn rename_entity_response_action_is_renamed() {
177        let resp = RenameEntityResponse {
178            action: "renamed".to_string(),
179            old_name: "x".to_string(),
180            new_name: "y".to_string(),
181            entity_id: 1,
182            namespace: "ns".to_string(),
183            elapsed_ms: 1,
184        };
185        assert_eq!(resp.action, "renamed");
186    }
187
188    #[test]
189    fn rename_entity_response_entity_id_preserved() {
190        let resp = RenameEntityResponse {
191            action: "renamed".to_string(),
192            old_name: "old".to_string(),
193            new_name: "new".to_string(),
194            entity_id: 999,
195            namespace: "test-ns".to_string(),
196            elapsed_ms: 5,
197        };
198        let json = serde_json::to_value(&resp).expect("serialization failed");
199        assert_eq!(json["entity_id"], 999);
200    }
201
202    #[test]
203    fn rejects_rename_entity_to_same_name() {
204        use crate::errors::AppError;
205        let err = AppError::Validation("source and target entity names are identical".to_string());
206        assert_eq!(err.exit_code(), 1);
207        assert!(err.to_string().contains("identical"));
208    }
209
210    #[test]
211    fn rename_entity_response_namespace_reflected() {
212        let resp = RenameEntityResponse {
213            action: "renamed".to_string(),
214            old_name: "a".to_string(),
215            new_name: "b".to_string(),
216            entity_id: 10,
217            namespace: "my-project".to_string(),
218            elapsed_ms: 2,
219        };
220        let json = serde_json::to_value(&resp).expect("serialization failed");
221        assert_eq!(json["namespace"], "my-project");
222    }
223}
sqlite_graphrag/commands/rename_entity.rs

sqlite_graphrag/commands/
rename_entity.rs
