delete_metadata() │ WP 2.9.0

Deletes the metadata of the specified object (post, user, comment).

The function calls the filter delete_(meta_type)_meta before deleting the data and the filter deleted_(meta_type)_meta after deleting the data.

Used By: delete_post_meta_by_key(), delete_term_meta(), delete_user_meta(), delete_comment_meta(), delete_post_meta()

Returns

true|false. true if the metadata was successfully deleted or false.

Usage

delete_metadata( $meta_type, $object_id, $meta_key, $meta_value, $delete_all );

$meta_type(string) (required): The type of object the function will work with. For example: post, user, comment, term.
$object_id(int) (required): ID of the object whose metadata needs to be deleted. For example, the ID of the post.
$meta_key(string) (required): The name of the metadata key to be deleted. For example: the custom field key of the post "title".
$meta_value(string/array/int/object/boolean): If this value is specified, the function will attempt to find and delete metadata with the value specified here when one object has different metadata with the same keys. For example, post 5 has custom fields: title=value 1 and title=value 2, we need to delete "value 2", we specify it in this parameter.
Default: ''
$delete_all(boolean): If this parameter is set to true, the function will ignore the $object_id parameter and delete the specified metadata from all objects. By default false - metadata is deleted only from the specified object.
Default: false

Examples

#1 Code of delete_post_meta() function

The function code is from /wp-includes/post.php:

function delete_post_meta( $post_id, $meta_key, $meta_value = '' ) {

	// Make sure meta is added to the post, not a revision.
	$the_post = wp_is_post_revision( $post_id );
	if ( $the_post ) {
		$post_id = $the_post;
	}

	return delete_metadata( 'post', $post_id, $meta_key, $meta_value );
}

#2 Delete the post custom field

Let's remove the custom field with the "title" key from post 25:

delete_metadata( 'post', 25, 'title' );

#3 Delete all meta-fields from the whole database

This code shows how to delete all metafields of all posts with the specified key:

$meta_key = 'key_to_delete';
$deleted = delete_metadata( 'post', 0, $meta_key, '', true ); 

if( $deleted ){
	echo "All post meta fields with key $meta_key deleted.";
}
else {
	echo "Nothing deleted.";
}

Or use such more descriptive code:

/*
 * Remove all post meta data for Custom Post Type (CPT)
 * at the time of uninstall of plugin that created this CPT.
 * So that plugin do not leave behind any orphan post meta data
 * related to its CPT. 
 * 
 * You may place this code in uninstall.php file in your plugin root directory.
 */
$meta_type  = 'post';           // since we are deleting data for CPT 
$object_id  = 0;                // no need to put id of object since we are deleting all
$meta_key   = 'my_meta_key';    // Your target meta_key added using update_post_meta()
$meta_value = '';               // No need to check for value since we are deleting all
$delete_all = true;             // This is important to have TRUE to delete all post meta

// This will delete all post meta data having the specified key 
delete_metadata( $meta_type, $object_id, $meta_key, $meta_value, $delete_all );

#4 Be VERY careful

Be VERY careful when using this function to delete a specific key-value pair. As stated, providing an empty string for $meta_value will cause the check to be skipped entirely, resulting in all keys being deleted!

$meta_value …If specified, only delete metadata entries with this value. Otherwise, delete all entries with the specified meta_key…

To avoid accidentally deleting ALL key instances, use a short-circuit check:

$value_to_delete = get_value(); // may return empty string

if ( $value_to_delete && delete_metadata( 'post', 27, 'key', $value_to_delete ) ) {
	// the key-value pair was safely deleted
}

Notes

Global. wpdb. $wpdb WordPress database abstraction object.

Changelog

Since 2.9.0

Introduced.

`delete_metadata() delete metadata` code ^{WP 6.9.1}

wp-includes/meta.php

function delete_metadata( $meta_type, $object_id, $meta_key, $meta_value = '', $delete_all = false ) {
	global $wpdb;

	if ( ! $meta_type || ! $meta_key || ! is_numeric( $object_id ) && ! $delete_all ) {
		return false;
	}

	$object_id = absint( $object_id );
	if ( ! $object_id && ! $delete_all ) {
		return false;
	}

	$table = _get_meta_table( $meta_type );
	if ( ! $table ) {
		return false;
	}

	$type_column = sanitize_key( $meta_type . '_id' );
	$id_column   = ( 'user' === $meta_type ) ? 'umeta_id' : 'meta_id';

	// expected_slashed ($meta_key)
	$meta_key   = wp_unslash( $meta_key );
	$meta_value = wp_unslash( $meta_value );

	/**
	 * Short-circuits deleting metadata of a specific type.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (blog, post, comment, term, user, or any other type with an associated meta table).
	 * Returning a non-null value will effectively short-circuit the function.
	 *
	 * Possible hook names include:
	 *
	 *  - `delete_blog_metadata`
	 *  - `delete_post_metadata`
	 *  - `delete_comment_metadata`
	 *  - `delete_term_metadata`
	 *  - `delete_user_metadata`
	 *
	 * @since 3.1.0
	 *
	 * @param null|bool $delete     Whether to allow metadata deletion of the given type.
	 * @param int       $object_id  ID of the object metadata is for.
	 * @param string    $meta_key   Metadata key.
	 * @param mixed     $meta_value Metadata value. Must be serializable if non-scalar.
	 * @param bool      $delete_all Whether to delete the matching metadata entries
	 *                              for all objects, ignoring the specified $object_id.
	 *                              Default false.
	 */
	$check = apply_filters( "delete_{$meta_type}_metadata", null, $object_id, $meta_key, $meta_value, $delete_all );
	if ( null !== $check ) {
		return (bool) $check;
	}

	$_meta_value = $meta_value;
	$meta_value  = maybe_serialize( $meta_value );

	$query = $wpdb->prepare( "SELECT $id_column FROM $table WHERE meta_key = %s", $meta_key );

	if ( ! $delete_all ) {
		$query .= $wpdb->prepare( " AND $type_column = %d", $object_id );
	}

	if ( '' !== $meta_value && null !== $meta_value && false !== $meta_value ) {
		$query .= $wpdb->prepare( ' AND meta_value = %s', $meta_value );
	}

	$meta_ids = $wpdb->get_col( $query );
	if ( ! count( $meta_ids ) ) {
		return false;
	}

	if ( $delete_all ) {
		if ( '' !== $meta_value && null !== $meta_value && false !== $meta_value ) {
			$object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s AND meta_value = %s", $meta_key, $meta_value ) );
		} else {
			$object_ids = $wpdb->get_col( $wpdb->prepare( "SELECT $type_column FROM $table WHERE meta_key = %s", $meta_key ) );
		}
	}

	/**
	 * Fires immediately before deleting metadata of a specific type.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (blog, post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible hook names include:
	 *
	 *  - `delete_blog_meta`
	 *  - `delete_post_meta`
	 *  - `delete_comment_meta`
	 *  - `delete_term_meta`
	 *  - `delete_user_meta`
	 *
	 * @since 3.1.0
	 *
	 * @param string[] $meta_ids    An array of metadata entry IDs to delete.
	 * @param int      $object_id   ID of the object metadata is for.
	 * @param string   $meta_key    Metadata key.
	 * @param mixed    $_meta_value Metadata value.
	 */
	do_action( "delete_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );

	// Old-style action.
	if ( 'post' === $meta_type ) {
		/**
		 * Fires immediately before deleting metadata for a post.
		 *
		 * @since 2.9.0
		 *
		 * @param string[] $meta_ids An array of metadata entry IDs to delete.
		 */
		do_action( 'delete_postmeta', $meta_ids );
	}

	$query = "DELETE FROM $table WHERE $id_column IN( " . implode( ',', $meta_ids ) . ' )';

	$count = $wpdb->query( $query );

	if ( ! $count ) {
		return false;
	}

	if ( $delete_all ) {
		$data = (array) $object_ids;
	} else {
		$data = array( $object_id );
	}
	wp_cache_delete_multiple( $data, $meta_type . '_meta' );

	/**
	 * Fires immediately after deleting metadata of a specific type.
	 *
	 * The dynamic portion of the hook name, `$meta_type`, refers to the meta object type
	 * (blog, post, comment, term, user, or any other type with an associated meta table).
	 *
	 * Possible hook names include:
	 *
	 *  - `deleted_blog_meta`
	 *  - `deleted_post_meta`
	 *  - `deleted_comment_meta`
	 *  - `deleted_term_meta`
	 *  - `deleted_user_meta`
	 *
	 * @since 2.9.0
	 *
	 * @param string[] $meta_ids    An array of metadata entry IDs to delete.
	 * @param int      $object_id   ID of the object metadata is for.
	 * @param string   $meta_key    Metadata key.
	 * @param mixed    $_meta_value Metadata value.
	 */
	do_action( "deleted_{$meta_type}_meta", $meta_ids, $object_id, $meta_key, $_meta_value );

	// Old-style action.
	if ( 'post' === $meta_type ) {
		/**
		 * Fires immediately after deleting metadata for a post.
		 *
		 * @since 2.9.0
		 *
		 * @param string[] $meta_ids An array of metadata entry IDs to delete.
		 */
		do_action( 'deleted_postmeta', $meta_ids );
	}

	return true;
}