wp_delete_object_term_relationships() │ WP 2.3.0

Destroys all relationships of the object (post, page) with the specified taxonomy(ies).

Will remove all relationships between all elements of the specified taxonomy (terms) and the specified object (post, page, link, custom post type, etc.). The taxonomy object (term) itself is not deleted - only the relationship with it is destroyed.

With this function, for example, you can remove all tags from the specified post without deleting the tags themselves (i.e., destroy the relationship between the post and the tags). Similarly, it can be applied to custom taxonomies.

To remove the relationship of an object with a specific taxonomy element (and not all at once), use wp_remove_object_terms().

Uses: wp_remove_object_terms()

No Hooks.

Returns

null. Returns nothing.

Usage

<?php wp_delete_object_term_relationships( $object_id, $taxonomies ); ?>

$object_id(integer) (required): ID of the object whose relationship with the taxonomy needs to be destroyed. The object can be the ID of a post, page, attachment, etc.
$taxonomies(string/array) (required): The name of the taxonomy or a list of taxonomy names whose relationship needs to be destroyed.

Examples

#1 Remove the tags from the post

Let's say there are tags "one" and "two" that are attached to post 567 and we need to remove this relationship (remove tags from the post):

<?php wp_delete_object_term_relationships( 567, 'post_tag' ); ?>

Delete multiple taxonomies’ relationships for a post

$post_id = 55;
$taxonomies = [ 'category', 'post_tag', 'custom_taxonomy' ];

wp_delete_object_term_relationships( $post_id, $taxonomies );

#2 Dividing the posts between the two taxonomies

Suppose we have two taxonomies music and compositors and some posts that are in terms of both these taxonomies. And we need to select all the posts that are in the music taxonomy and remove them from the compositors taxonomy, if there is a relation to compositors at all.

Thus, we will split all the posts into two taxonomies and the post will be in either music or compositors.

del_tax_rel( $leave_in = 'music', $del_from = 'compositors' );

function del_tax_rel( $leave_in, $del_from ) {
	global $wpdb;

	$sql = "SELECT p.ID, post_title
	FROM $wpdb->posts p
		JOIN $wpdb->term_relationships rel ON (rel.object_id = p.ID)
		JOIN $wpdb->term_taxonomy tx ON (rel.term_taxonomy_id = tx.term_taxonomy_id)
	WHERE p.post_status = 'publish'
		AND tx.taxonomy = '$leave_in'";

	$results = $wpdb->get_results( $sql );

	if( ! $results ){
		return false;
	}

	foreach( $results as $pst ){
		wp_delete_object_term_relationships( $pst->ID, $del_from );
	}
}

#3 Remove the post from this category

Let's remove post 10 from term (category) 1, i.e. let's break the relation of the specified object (post, page) with an element of the taxonomy (term):

$object_id = 10;
$delete_terms = [ 1 ];

global $wpdb;

if( $delete_terms ){

	$in_delete_terms = "'" . implode( "', '", $delete_terms ) . "'";

	do_action( 'delete_term_relationships', $object_id, $delete_terms );

	$wpdb->query( $wpdb->prepare( 
		"DELETE FROM $wpdb->term_relationships WHERE object_id = %d AND term_taxonomy_id IN ($in_delete_terms)", 
		$object_id 
	) );

	do_action( 'deleted_term_relationships', $object_id, $delete_terms );

	wp_update_term_count( $delete_terms, $taxonomy );
}

You can specify several taxonomy elements in an array: [ 1, 2, 67 ].

This example doesn't exactly fit this function, but it is similar because it also breaks the relationship between an object and a taxonomy element. The difference is that here only 1 or more specified elements are broken, while wp_delete_object_term_relationships() breaks all relationships to the taxonomy at all.

Notes

Uses the filter (action) delete_term_relationships, triggered before the relationship is deleted.
Uses the filter (action) deleted_term_relationships, triggered after the relationship is deleted.

Changelog

Since 2.3.0

Introduced.

`wp_delete_object_term_relationships() wp delete object term relationships` code ^{WP 6.9}

wp-includes/taxonomy.php

function wp_delete_object_term_relationships( $object_id, $taxonomies ) {
	$object_id = (int) $object_id;

	if ( ! is_array( $taxonomies ) ) {
		$taxonomies = array( $taxonomies );
	}

	foreach ( (array) $taxonomies as $taxonomy ) {
		$term_ids = wp_get_object_terms( $object_id, $taxonomy, array( 'fields' => 'ids' ) );
		$term_ids = array_map( 'intval', $term_ids );
		wp_remove_object_terms( $object_id, $term_ids, $taxonomy );
	}
}